推荐 序 一 一 一 REST 开 发 的 理想 与 现实 


REST 是 一 种 分 布 式 应 用 的 架构 风格 ， 也 是 一 种 大 流量 分 布 式 应 用 的 设计 方法 论 。REST 是 由 (构成 了 Web 基 础 架构 的 ) HTTP、URI 等 规范 的 主要 设计 者 Roy Fileding 博 士 在 其 2000 年 的 博士 论文 (中 文 


版 名 为 《架构 风格 与 基于 网 络 应 


REST 就 是 Web (World Wide Web， 简 称 Web 或 者 WWW) 本 身 的 架构 风格 ， 是 设计 、 开 发 Web 相 关 规 范 、Web 应 上 


软件 的 架构 设计 》) 中 提出 的 。 到 目前 为 止 ， 关 于 REST 最 系统 、 最 全 面 的 论述 ， 仍 然 是 Fielding 的 博士 论文 。 


、Web 服 务 的 指导 原则 。 不 符合 REST 风 格 要 求 的 架构 和 技术 ， 很 难 在 Web 这 个 


生态 系统 中 得 到 繁荣 发 展 。 在 我 看 来 ，Roy Fielding 博 士 就 是 15 年 以 来 对 于 分 布 式 应 用 架构 设计 理论 贡献 最 大 的 人 。Fielding 在 HTTP 规 范 的 设计 过 程 中 ， 并 没有 采用 当时 大 行 其 道 的 DO (Distributed 
Object， 分 布 式 对 象 ) 风格 ， 而 是 自 出 机 标 、 另 辟 蹊 径 ， 提 出 了 一 整套 新 的 设计 方法 论 。Fielding 的 开创 性 工作 ， 极 大 地 推动 了 分 布 式 应 用 设计 理论 的 发 展 。 


有 趣 的 是 ， 其 实 基 于 SOAP/WSDL 的 “大 Web Service” 


(以 下 简称 Web Service) ,几乎 是 与 REST 同 时 发 展 起 来 的 。 虽 然 在 Web Service 中 也 使 用 了 对 象 ,但 是 Web Service 其 实 是 RPC 风 格 的 ,而 不 


是 DO 风格 的 。Web Service 在 最 初 几 年 发 展 很 快 ， 很 大 原因 是 它 解决 了 DO 风格 难以 解决 的 异 构 系统 (不同 的 硬件 系统 、 不 同 操作 系统 、 不 同 的 编程 语言 ， 等 等 ) 之 间 互 操作 性 的 问题 。 


然而 遗憾 的 是 ， 设 计 Web Service 协 议 栈 的 核心 人 员 ， 几 乎 都 是 来 自 于 企业 应 用 阵营 的 ， 尤 其 是 来 自 于 IBM 和 微软 两 家 公司 的 人 。 这 些 企 业 应 用 的 专家 们 没有 充分 认识 到 Web 基 础 架构 的 巨大 优点 ， 甚 
至 可 以 说 并 没有 理解 HTTP 协 议 究竟 是 用 来 做 什么 的 、 为 何 要 如 此 设计 。 在 Web Service 协 议 栈 的 设计 之 中 ,仍然 有 深 深 的 企业 应 用 


复杂 性 很 高 ， 在 实战 中 互 操作 性 并 不 好 (例如 升级 过 程 困难 而 且 复杂 ) 。 此 外 ，Web Service 仅 仅 将 HTTP 协 议 当 做 一 种 传输 协议 来 使 用 ， 还 依赖 XML 这 种 元 余 度 很 高 的 文本 格式 ， 这 导致 Web Service 应 


痕迹 。Web Service 虽 然 宣称 能 够 很 好 地 支持 互 操 作 ， 然 而 因为 协议 栈 的 


性 能 低下 。 很 多 开发 团队 宁可 使 用 Hessian 等 轻 量 级 的 RPC 协 议 ， 也 不 愿意 使 用 Web Service。 在 面向 互联 网 的 大 流量 Web 应 用 (包括 Web 服 务 在 内 ) 这 种 运行 环境 中 ，Web service 在 复杂 性 、 互 操作 性 、 
性 能 、 可 伸缩 性 等 方面 的 短 板 更 加 突出 。 因 此 ， 设 计 今日 面向 互联 网 的 AP1， 已 经 很 少 有 人 会 考虑 Web Service。 这 使 得 Web Service 的 使 用 被 局 限 在 企业 应 用 运行 环境 之 中 ， 其 名 称 中 的 “Web” 更 像 是 一 


个 笑话 (除了 都 使 


HTTP 协 议 ， 基 本 上 与 Web 没 什么 关系 ) 。 假 如 在 2000 年 ， 设 计 Web Service 规 范 的 专家 们 ， 能 够 认真 读 一 下 F 


人 员 深 入 交流 一 下 ，Web Service 很 可 能 就 不 是 现在 这 个 样子 了 。 不 过 ， 历 史 是 无 法 假设 的 。 


ielding 的 博士 论文 ， 或 者 找 HTTP、URI 等 Web 基 础 架构 规范 的 核心 设计 


在 Java 世 界 中 ， 与 大 Web Service 相 对 应 的 规范 是 JAX-WS。 在 大 Web Service 已 经 成 为 明日 黄花 之 后 ，Java 世 界 急需 一 套 新 的 规范 来 取代 JAX-WS。 这 套 新 的 规范 就 是 JAX-RS: Java 世 界 开发 RESTful 
Web Service (与 RESTful API 含 义 相 同 ， 可 混用 ) 的 规范 。 虽 然 起 步 很 晚 ， 毕 竟 走 上 了 正确 的 道路 。 


从 Java EE 6; 


始 ，JAX-RS 在 Java EE 版 图 中 ， 作 为 最 重要 的 组 成 部 分 之 一 ， 逐 步 取代 了 JAX-WS 的 地 位 。 在 所 有 Java EE 相关 规范 中 ，JAX-RS 是 优点 很 突出 的 一 个 。 例 如 ， 完 全 基于 POJO、 很 容易 做 单 


元 测试 、 将 HTTP 作 为 一 种 应 用 协议 而 不 是 可 替代 的 传输 协议 (因此 提高 了 性 能 ) 、 优 秀 的 IDE 集 成 ， 等 等 。 可 以 说 ， 在 大 多 数 场合 
术 。JAX-RS 同 样 也 可 以 完全 取代 Hessian 等 基于 HTTP 协 议 的 RPC 风 格 远程 调用 协议 。 毕 竟 HTTP 本 身 就 是 一 种 REST 风 格 的 应 用 协议 


Jersey、CXF 等 支持 JAX-RS 规 范 的 REST 开 发 框架 还 支持 加 


代 JAX-Ws 的 角度 来 看 ，JAX-RS 已 经 做 得 非常 棒 了 。 


出 WADL。WADL 支 持 客户 端 代码 自动 生成 ， 还 可 以 将 WADL 导 入 到 SoapUl 等 测试 工具 中 ， 然 后 


，JAX-RS 完 全 可 以 取代 JAX-WS， 作 为 Java Web Service 开 发 的 主要 技 
， 以 REST 风 格 来 使 用 HTTP， 才 是 最 高 效 的 使 用 方式 。 


做 自动 化 集成 测试 。 从 开发 java 企业 应 用 、 取 


尽管 如 此 ， 不 可 不 提 的 是 ，JAX-RS 这 套 规范 ， 仍 然 存 在 着 很 多 遗憾 。 需 要 特别 指出 的 是 ，JAX-RS 规 范 并 不 等 于 REST 架 构 风格 本 身 ，REST 的 内 涵 要 比 JAX-RS 广 泛 得 多 。 学 会 了 使 用 JAX-RS 了 ， 并 不 等 


于 就 完全 理解 了 REST， 开 发 者 仍然 需要 下 工夫 认真 学 习 一 下 本 源 的 REST 究 竟 是 什么 。 


例如 ，JAX-Rs 规 范 对 于 应 该 如 何 定义 一 个 资源 ， 以 及 应 该 如 何 使 用 HTTP 作 为 一 个 统一 接口 来 操作 资源 ， 显 然 缺 乏 必要 的 指导 。 


一 个 资源 接口 。 接 


的 方法 太 多 ， 导 致 映射 到 的 HTTP 方 法 不 够 用 ， 这 也 难 不 倒 他 们 ， 在 URI 路 径 中 加 一 些 字符 串 就 能 够 解决 (例如 


常常 见 ， 虽 然 开发 者 使 用 了 JAX-Rs 规 范 ， 但 是 开发 方式 完全 是 RPC 风 格 的 ， 可 以 说 与 REST 风 格 没 有 任何 关系 。 


此 外 ，JAX-Rs 规 范 目前 尚 不 支持 HATEOAS (将 超 文本 作为 应 用 状态 的 引擎 ，REST 风 格 的 核心 特征 之 一 ) ， 从 著名 的 Richards 
量 ， 基 于 JAX-RSs 规 范 实现 的 RESTful API 仅 仅 能 够 达到 成 熟 度 模型 的 第 二 级 ， 即 支持 资源 抽象 、 统 一 接口 的 “CRUD 式 Web 服 务 ”。 


可 以 这 样 说 ，JAX-RS 规 范 与 真正 的 REST 风 格 ， 覆 盖 的 范 上 


并 不 高 ， 仅 仅 是 希望 使 用 HTTP 本 身 来 取代 大 Web Service 作 为 一 种 轻 量 级 、 容 易 测试 的 远程 调用 协议 。REST 架 构 风格 的 严格 要 求 ， 


是 为 了 解决 手头 的 


如 果 按 照 Roy Fielding 博 士 的 严格 要 求 (REST APls must be hyper-text driven) ， 那 么 包括 JAX-RS 规 范 在 | 
Richardson 成 熟 度 模型 第 一 级 ， 即 有 清晰 的 资源 抽象 ， 就 可 以 认为 是 RESTful API 了 。 如 果 连 第 一 级 都 达 不 到 


API 阵 营 里 面 挤 了 。 


况 。JAX-RS 反 映 的 


韩 陆 兄 的 新 著 


因此 ， 能 够 完美 支持 HATEOAS， 攀 登 到 成 熟 度 模型 第 三 级 ， 是 一 种 理想 情况 ( 


可 题 ，JAX-Ws 并 不 好 用 ，JAX-Rs 解 救 了 他 们 。 


正 是 这 种 现实 情况 ， 从 实战 的 角度 ， 它 是 一 套 非常 有 用 也 很 好 用 的 规范 。 


有 很 多 开发 者 只 是 简单 地 将 以 前 JAX-WS 中 的 一 个 endpoint 接 口 转换 成 
， 三 个 接口 方法 都 映射 到 POST， 但 是 其 PATH 不 同 ) 。 这 样 的 开发 方式 非 


on 成 熟 度 模型 (由 《RESTful Web APls》 的 作者 Richardson 提 出 ) 来 稀 


其 实 是 不 同 的 。JAX-RS 覆 盖 的 是 简单 基于 HTTP 协 议 (没有 使 用 SOAP/WSDL) 的 各 种 远程 调用 需求 ， 很 多 需求 对 于 可 伸缩 性 、 松 耦合 的 要 求 


在 这 些 场合 并 不 是 非常 重要 。 情 懒 是 人 类 的 天 性 ， 大 多 数 开发 者 写 代码 只 


内 都 不 能 算是 真正 的 RESTful。 然 而 ， 从 实战 角度 ， 我 认为 革命 不 分 先后 ， 只 要 能 够 达到 
， 所 设计 的 架构 根本 就 不 是 面向 资源 的 ， 那 八成 还 是 RPC 风 格 的 ， 就 没有 必要 非 要 往 RESTful 
从 来 没有 人 说 过 RPC 就 是 万 恶 的 ，RPC 在 企业 应 用 的 大 多 数 场合 其 实 都 非常 有 效 ， 只 是 不 适合 面向 互联 网 的 大 流量 Web 应 用 而 已 。 


当然 也 是 值得 追求 的 ) 。 而 通过 部 分 拥抱 REST 风 格 的 要 求 ， 来 更 好 地 解决 手头 的 问题 ， 是 更 多 开发 者 所 面 对 的 现实 情 


《Java RESTful Web Service 实 战 》 是 JAX-RS 规 范 方面 的 专著 ， 也 是 国内 第 一 本 REST 开 发 的 原创 著作 。 这 本 书 的 实战 性 非常 强 ， 全 面 介绍 了 JAX-RS 2.0 的 方方面面 ， 可 以 作为 一 线 Java 分 


布 式 应 用 开发 者 的 案头 必 备 书 。 如 同 我 在 前 面 所 指出 的 ，JAX-RS 规 范 并 不 等 于 REST 架 构 风 格 本 身 ， 它 们 有 着 不 同 的 覆盖 范围 。 在 本 书 中 ， 作 者 也 介绍 了 很 多 设计 RESTful API 的 最 佳 实践 ， 这 些 内 容 假 如 读 


者 不 理解 REST， 甚 至 在 亲自 阅读 了 JAX-RS 规 范 之 后 也 未 必 能 够 总 结 出 来 。 读 者 在 阅读 本 书 的 过 程 中 ， 不 应 该 仅仅 满足 于 掌握 了 JAX-RS 开 发 的 基本 方法 、 解 决 了 手头 的 问题 、 用 其 完全 取代 JAX-WS， 更 重要 


的 是 ， 读 者 还 应 该 就 REST 架 构 风格 本 身 做 更 多 的 学 习 。 幸 运 的 是 ， 除 了 本 书 之 外 ， 目 前 REST 设 计 和 开发 方面 的 图 书 资料 已 经 非常 多 了 。 


本 书 的 内 容 非 常 严 谨 ， 有 非常 好 的 系统 性 ， 对 于 设计 开发 大 流量 Web 服 务 会 面临 的 各 种 问题 都 有 涉及 。 特 别 是 在 自动 化 测试 方 
常 重要 ， 需 要 在 设计 之 初 就 充分 考虑 到 。 本 书 是 一 本 难得 的 原创 佳作 ， 值 得 所 有 Java 分 布 式 应 用 的 开发 者 购买 。 


理想 富丽 丰满 ， 


面 着 墨 颇 多 ， 在 我 看 来 是 本 书 的 一 大 亮点 。RESTful API 的 自动 化 测试 非 


现实 贫 羌 骨 感 ， 追 求 理想 和 注重 解决 现实 问题 其 实 并 不 矛盾 。JAX-RS 规 范 的 发 展 ， 反 映 出 了 Java 社 区 在 更 好 地 


发 RESTful Web Service 方 面 的 求索 。 尽 管 存 在 争议 ， 在 我 看 来 ， 规 范 


化 是 推动 RESTful Web Service 取 得 更 大 发 展 的 必由之路 。 目 前 对 于 优秀 的 RESTful API 有 哪些 判断 标准 ，Web 开 发 者 社区 已 经 达成 了 高 度 共识 ， 也 积累 了 大 量 非常 有 价值 的 成 果 。JAX-RS 规 范 的 发 展 ， 离 


不 开 Web 开 发 者 社 
步 ， 任 重 而 道 远 。 


区 的 这 些 成 果 。 在 未 来 的 JAX-RS 3.0 规 范 中 ， 我 们 将 会 看 到 更 多 令 人 兴奋 的 成 果 被 规范 化 。JAX-RS 2.0 已 经 做 得 不 错 了 ， 但 是 在 RESTful Web Service 规 范 化 的 道路 上 ， 


推荐 序 二 


实 才 刚刚 起 


半年 前 初 识 韩 陆 的 时 候 ， 我 们 就 聊 到 他 正在 写 的 这 本 书 ， 当 得 知 我 从 2006 年 就 参与 了 Apache CXF 开 发 ， 他 立即 邀请 我 为 他 的 新 书写 序 ， 我 也 就 欣然 答应 了 。 


Apache CXF 作 为 JAXWS 以 及 JAX-RS 规 范 的 实现 框架 ， 已 经 成 为 很 多 Web 服 务 开发 者 必 选 的 开发 框架 。 作 为 这 一 框架 的 开发 维护 者 之 一 ， 我 的 日 常 工作 经 常 需要 熟悉 这 些 JSR 规 范 ， 并 实现 JSR 所 定义 的 
AP1， 解 决 最 终 用 户 的 使 用 问题 。 


熟悉 Java 的 人 大 多 都 听 说 过 JSR (Java Specification Requests) 、JCP (Java Community Process) ， 通 过 JSR 可 以 就 java 某 一 方面 的 应 用 定义 一 组 标准 的 AP| 或 者 服务 。 对 于 最 终 用 户 来 说 ， 他 们 的 
代码 只 需要 调用 JSR 定 义 的 标准 APl， 不 做 任何 修改 就 可 以 调用 不 同 的 JSR 实 现 。 这 里 常见 的 例子 就 是 Java Servlet 应 用 ， 用 户 开 发 的 Web 应 用 可 以 不 做 任何 修改 就 部 署 到 Tomcat、JBoss 等 不 同 的 Web 容 器 
中 。 


JAXRS 是 JCP 为 Java RESTful Web Service 定 义 的 一 套 APl。 由 于 Web 服 务 的 描述 模型 与 Java 类 和 接口 有 一 定 的 差距 ，JAX-RS 定 义 了 很 多 annotation， 通 过 这 些 annotation 我 们 可 以 很 方便 地 将 Java 类 
描述 成 为 相关 的 REST 服 务 。 由 于 RESTful Web Service 通 常 需要 部 署 到 Web 容 器 中 ，JAX-RS 也 定义 了 相关 服务 来 发 现 部 署 到 容器 中 的 JAX-RS 应 用 。 


读 过 JSR 规 范 的 朋友 或 多 或 少 都 会 有 这 样 的 体会 ，JSR 作 为 规范 文档 ， 其 目标 是 将 API 定 义 以 及 实现 功能 描述 清楚 、 完 备 ， 其 目标 读者 是 相关 API 的 实现 人 员 ， 或 者 是 相关 API 的 高 级 使 用 人 员 。 如 果 读 者 
对 相关 的 背景 知识 还 不 熟悉 的 话 ，JSR 文 档 读 起 来 会 比较 星 涩 而 且 难 以 理解 。 加 之 绝 大 部 分 SR 文档 都 没有 相关 的 中 文 翻译 ， 对 于 绝 大 多 数 初 学 者 来 说 ， 通 过 阅读 JSR 文 档 来 学 习 相 关 的 API 的 知识 是 一 个 艰难 
的 过 程 。 


如 果 我 们 想 要 对 JAX-Rs 规 范 有 一 个 比较 快速 并 且 全 面 的 了 解 应 该 怎么 办 呢 ? 一 般 来 我 们 可 以 通过 JSR 的 相关 参考 实现 入 手 ， 我 们 不 但 可 以 通过 运行 相关 的 参考 实现 的 例子 快速 入 门 ， 还 可 以 通过 跟踪 相 
关 的 代码 对 实现 细节 有 一 个 全 面 的 了 解 。 韩 陆 的 这 本 新 作 以 JAX-RS 的 参考 实现 Jersey 为 蓝本 ， 由 浅 入 深 地 向 大 家 介绍 了 JAX-RS 的 由 来 ， 以 及 与 RESTful Web 服 务 开发 的 相关 AP1， 并 结合 实例 分 享 了 作者 的 
实战 经 验 。 


好 了 ， 现 在 打开 你 熟悉 的 IDE 工 具 ， 加 载 Jersey 代 码 库 ， 沿 着 本 书 的 指引 去 探索 Java RESTful Web Services 开 发 世界 吧 。 


RedHat 姜 宁 


加 
下 


从 我 启动 本 书 到 完稿 ， 历 时 一 年 有 余 。 


此 间 ，Java EE 7 得 到 了 更 多 服务 器 软件 的 支持 ，Jersey 升 级 了 9 个 小 版 本 一 一 我 在 动笔 开始 文字 和 示例 代码 编写 的 时 候 ，Jersey 刚 刚 推出 2.0 版 本 ， 到 本 书 完毕 时 ， 版 本 号 是 2.9， 这 也 是 本 书 的 最 终 版 
本 。 此 后 新 版 本 带 来 的 改变 只 有 通过 本 书 提供 的 源 代码 来 同步 更 新 。 


此 间 ， 我 积极 参与 和 关注 着 Jersey 项 目的 动向 ， 通 过 关注 Jersey 官 方 文档 、Jersey 在 GitHub 托 管 系统 的 源 代 码 、Jersey 的 Jira 缺 陷 管理 系统 、Jersey 的 StackOverflow 问 答 系 统 ， 对 其 修复 缺陷 、 引 入 新 
功能 和 如 何 使 用 Jersey 等 事宜 不 断 跟 进 。 


我 之 所 以 这 么 做 ， 目 的 只 有 一 个 ， 即 希望 为 读者 呈现 的 是 一 本 Java 领 域 RKEST 开 发 的 好 书 。 


为 什么 要 写 这 本 书 


REST 式 的 Web 服 务 有 多 流行 ， 相 信 每 一 位 翻阅 本 书 的 读者 都 很 清楚 ， 冒 昧 地 猜测 ， 你 可 能 想 要 看 到 的 是 一 本 讲述 如 何 使 用 java 语言 和 java EE 平 台 ， 来 实现 这 一 风格 的 服务 或 者 应 用 的 书 。 这 也 正 是 我 
这 两 年 来 努力 写作 的 初 心 和 原动力 。 我 相信 ， 读 者 希望 看 到 的 内 容 不 单单 是 追逐 流行 、 风 摩 一 时 的 “快餐 ”。 作 为 开发 者 ， 我 知道 拥有 对 新 技术 、 新 标准 的 敏锐 嗅觉 非常 重要 ， 但 我 认为 更 难能可贵 的 是 把 
一 个 业内 认可 的 标准 学 好 和 用 好 。Java EE 7 中 包含 了 JAX-RS 2.0 标 准 ， 是 Java 领 域 REST 式 的 Web 服 务 的 规范 ; GlassFish 是 Java EE 7 的 参考 实现 项 目 集 ，Jersey 是 其 子 项 目 ， 是 JAX-RS 2.0 的 参考 实现 。 本 
书 的 目的 就 是 要 把 JAX-RS 2.0 说 清楚 ， 把 如 何 用 Jersey 写 好 REST 式 的 服务 讲 明白 。 


是 


本 书 特色 
. 第 一 本 完整 讲述 使 用 Java 标 准 规范 实现 REST 的 书籍。 


“ 第 一 本 完整 讲述 以 JAX-RS 2.0 参 考 实现 实践 Jersey 的 书籍 。 


“ 给 出 深度 学 习 和 实践 JAX-RS 的 线路 图 和 解决 方案 。 


读者 对 象 


本 书 从 实践 角度 ， 完 整地 诠释 了 JAX-RS 2.0 (JSR 339) ， 即 Jersey 2.0 的 核心 元 素 和 REST 开 发 过 程 。 面 向 所 有 在 Java 领 域 学 习 和 使 用 REST 的 读者 。 同 样 欢迎 REST 领 域 的 其 他 语言 的 使 用 者 通过 本 书 了 
解 REST 的 实现 。 


“ 技术 路 线 : 架构 师 、 技 术 主管 、 研 发 工程 师 、REST 小 白 (网络 用 语 ， 本 书 指 新 手 ) ; 
' 管理 路 线 : 部 门 经 理 、 项 目 经 理 、 产 品 经 理 ; 


“ 敏捷 实践 者 。 


如 何 阅读 本 书 


本 书 收纳 了 笔者 近 三 年 的 RESTful| 实 战 经 验 ， 将 REST 理 论 与 Java 实 现 相 结合 ， 循 序 渐进 地 将 使 用 Java 开 发 REST 式 的 Web 服 务 中 遇 到 的 知识 点 和 经 验 呈现 给 读者 。 每 个 章节 中 的 知识 点 都 精心 设计 了 相应 
的 示例 代码 ， 便 于 读者 更 好 地 理解 和 更 及 时 地 进行 实践 。 从 第 11 章 开始 ， 笔 者 从 敏捷 角度 为 读者 呈现 了 一 个 完整 和 相对 复杂 的 REST 式 的 Web 服 务实 例 ， 相 信 这 个 实例 能 让 读者 更 好 地 理解 相关 内 容 ， 同 时 ， 
可 以 对 敏捷 开发 和 自动 化 测试 有 新 的 认识 。 


全 书 分 为 3 篇 ， 共 11 章 。 


第 一 篇 共 5 章 (第 1~5 章 ) ， 讲 述 REST 的 基本 理论 和 Jersey 的 基本 实践 。 完 成 第 一 篇 的 阅读 和 示例 代码 的 实践 ， 读 者 可 以 学 会 使 用 Java 开 发 REST 式 的 Web 服 务 的 基本 能 力 。 


第 1 章 


分 别 阐述 了 REST、REST 式 的 Web 服 务 、JAX-RS 2.0 和 Jersey 2.x 的 基本 情况 。 


第 2 


讲述 了 使 用 Jersey 2.x 开 发 一 个 基于 JAX-RS 2.0 标 准 的 应 用 的 基本 知识 以 及 如 何 使 用 Jersey 来 集成 Spring 和 JPA 以 快速 开发 一 个 REST 式 的 Web 服 务 。 本 章 包 含 10 个 示例 项 目 。 


深入 阐述 了 如 何 使 用 Jersey 设 计 和 实现 REST 式 的 Web 服 务 的 API。 本 章 包含 5 个 示例 项 目 。 


深入 阐述 了 Jersey 的 Providers 对 REST 请 求 的 处 理 。 


讲述 了 Jersey 的 客户 端 开 发 的 基本 实践 和 常用 配置 。 


二 篇 共 5 章 (第 6~10 章 ) ， 讲 述 写 好 REST 程 序 的 必要 知识 点 。 完 成 第 二 篇 的 阅读 和 实践 ， 读 者 可 以 全 面 了 解 如 何 写 好 一 个 完整 的 REST 式 的 Web 服 务 。 


全 面 讲述 了 如 何 实现 一 个 安全 的 REST 式 的 Web 服 务 。 


第 8 章 


第 9 章 


讲述 了 Jersey 的 测试 框架 及 其 使 用 。 


讲述 了 Jersey 对 HTML5 的 SSE 的 支持 和 异步 请 求 处 理 。 


讲述 了 Jersey 1.x 迁 移 到 Jersey 2.x 的 要 素 和 经 验 分 享 。 


第 10 章 ”分享 了 REST 式 的 Web 服 务 的 性 能 调 优 的 经 验 。 


宛 二 / 


包含 1 章 (第 11 章 ) ， 分 享 了 5 年 外 企 工 作 中 ， 我 对 自动 化 测试 和 敏捷 的 体会 。 完 成 本 部 分 内 容 的 阅读 和 实践 ， 读 者 可 以 更 宏观 地 审视 REST 的 应 用 场景 ， 起 到 抛砖引玉 的 作用 。 


第 11 章 ”讲述 一 个 完整 的 REST 项 目的 全 过 程 。 


全 文 由 三 个 小 版 组 成 : “阅读 指南 。、“ 小 白 讲 堂 ” (为 某 些 在 知识 点 上 比较 “小 白 ” 的 同学 介绍 概念 性 的 知识 ) 和 “ 宅 人 坑 事 ” (技术 宅 最 自豪 和 最 担 惊 受 怕 的 就 是 “ 踩 坑 ”) ， 旨 在 和 读者 分 享 基 


础 知识 和 心得 体会 ， 只 为 交流 ， 切 勿 对 号 入 座 。 


有 一 和 


推荐 研发 工程 师 和 REST 小 白 完 整 阅读 ， 这 部 分 包含 了 了 解 和 使 用 JAX-RS 2.0 完 成 学 习 和 工作 的 必要 章节 。 对 于 有 基础 的 技术 人 员 ， 可 以 作为 实践 的 参考 有 选择 地 阅读 。 


第 二 篇 推荐 致力 于 提高 自己 的 技术 人 员 完 整 阅读 ， 这 部 分 包含 了 JAX-RS 2.0 的 高 级 功能 。 永 不 满足 和 持续 学 习 的 精神 ， 会 让 你 在 关键 时 刻 成 为 “关键 先生 ”。 架构 师 和 项 目 经 理 在 考虑 安全 、 性 能 等 问 
题 时 ， 可 以 参考 相关 章节 。 


第 三 篇 推荐 渴望 实战 指导 的 技术 人 员 阅 读 和 跟随 实践 。 同 时 ， 该 篇 结合 了 笔者 参与 敏捷 实践 的 体会 ， 以 scrum 的 方式 进行 开发 管理 。 因 此 ， 敏 捷 实 践 者 和 相关 的 部 门 经 理 可 以 参考 。 


品 经 理 可 以 阅读 与 REST 特 性 相关 的 章节 ， 这 样 可 帮 你 在 设计 应 用 方面 有 所 提高 。 


源 代 码 
章节 源 代码 地 址 
第 1 章 ~ 第 10 章 https://github.com/feuyeux/Jax-rs2-guide 
第 11 章 https://github.com/feuyeux/jax-rs2-atup 
勘误 和 交流 


作为 开发 者 ， 非 常 欢迎 读者 能 与 我 一 起 交流 JAX-RS 2.0 相 关 的 技术 。 我 的 邮箱 是 : feuyeux@gmailcom， 新 浪 微 博 是 : 六 他 1_1。 


本 书 的 勘误 统计 在 https://github.com/feuyeux/jax-rs2-guide/wiki 中 ， 欢 迎 读者 批评 指正 。 
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第 一 篇 。 够 用 就 好 一 一 JAX-RS 2.0 基 础 


ms 第 1 章 JAX-RS 2.0 入 门 

和 第 2 章 JAX-RS 2.0 快 速 实现 
m 第 3 章 REST API 设 计 

@ 第 4 章 ”REST 请 求 处 理 


@ 第 5 章 ”REST 客 户 端 


第 1 章 JAX-RS 2.0 入 门 


本 章 逐 一 介绍 以 下 4 个 概念 : REST、REST 式 的 Web 服 务 、JAX-RS 标 准 和 Jersey 项 目 。 首 先 简要 介绍 一 下 这 4 个 概念 之 间 的 联系 : REST 是 一 种 跨 平 台 、 跨 语言 的 架构 风格 ，REST 式 的 Web 服 务 是 对 REST 
在 Web 领 域 的 实现 ;JAX-RS 标 准 是 在 Java 领 域 ， 对 REST 式 的 Web 服 务 制定 的 实现 标准 ，Jersey 是 JAX-RS 标 准 的 参考 实现 ， 是 Java EE 参考 实现 项 目 GlassFish 的 成 员 项 目 。 


1.1 解读 REST 


REST (Representational State Transfer， 表 述 性 状态 转移 ) ， 源 于 REST 之 父 Roy Thomas Fielding 博 士 在 2000 年 就 读 加 州 大 学 欧文 分 校 期 间 发 表 的 一 篇 学 术 论文 一 一 《Architectural Styles and 


the Design of Network-based Software Architectures》 [1]。 论 文中 提出 了 REST 的 6 个 特点 ,分 别 是 : 客户 端 -服务 器 的 、 无 状态 的 、 可 缓存 的 、 统 一 接口 、 分 层 系统 和 按 需 编码 。 在 此 不 敢 “ 班 门 弄 
和 荐 ” ， 希 望 读 者 阅读 一 下 这 部 开山 之 作 ， 以 此 理解 REST 产 生 的 原因 和 特点 。 


REST 具 有 跨 平台 、 跨 语言 的 优势 。 从 其 诞生 开始 ， 广 泛 地 得 到 了 诸多 语言 的 快速 支持 ， 比 较 著 名 的 是 ROR (Ruby on Rails) 。ROR 非 常 强调 规约 大 于 配置 的 理念 ， 这 一 理念 被 诸多 框架 和 工具 支持 
一 一 包括 以 Python 领域 的 Django、Groovy 领 域 的 Grails 为 代表 的 框架 ， 以 及 Maven、Gradle 为 代表 的 构建 工具 等 ， 但 REST 本 身 只 规定 了 面向 资源 ， 并 没有 包含 如 何 定义 和 约束 一 个 资源 的 标准 。 因 此 要 提 
示 读 者 ， 很 多 实现 了 REST 的 框架 和 工具 所 具备 的 特质 ， 其 全 部 特征 未 必 都 是 REST 定 义 的 ， 包 括 本 书 要 讲 的 JAX-RSs 标 准 的 定义 和 Jersey 等 JAX-RS 的 实现 。 


REST 在 众多 平台 和 语言 上 的 支持 ， 不 仅 包括 上 述 列举 的 传统 编程 语言 、 脚 本 语言 ， 还 包括 Nodejjs 这 样 新 兴 的 服务 器 端 脚本 语言 。REST 的 无 状态 ， 代 理 友好 性 等 优势 ， 使 对 其 支持 的 实现 更 加 方便 和 简 


人 Oj 二 南 指 南 至 于 为 什么 REST 的 出 现 影 响 了 今天 的 互联 网 ， 以 及 Web 的 发 展 历程 ， 可 参阅 附录 中 的 Web 简 史 。 


1.1.1 一 种 架构 风格 


REST 是 一 种 架构 风格 。 在 REST 架 构 风格 中 ， 对 象 被 抽象 为 一 种 资源 (resource) ， 资 源 的 命名 使 用 概念 清晰 的 名 词 来 定义 。 表 述 性 状态 是 对 资源 数据 在 某 个 瞬间 状态 的 快照 ， 资 源 的 某 个 瞬时 状态 被 
定义 为 一 种 表述 (representation) ， 这 种 描述 性 的 状态 包括 资源 数据 的 内 容 、 表 述 格 式 (比如 XML、JSON、Atom) 等 信息 ， 一 种 资源 可 以 对 应 多 种 表述 。REST 的 资源 是 可 寻 址 的 ， 通 过 HTTP 协 议 
(RFC 2616) 定义 的 通用 动词 方法 (比如 GET、PUT、DELETE、POST) ， 并 使 用 URI 协 议 (RFC 3305) 来 唯一 标识 某 个 资源 公布 出 来 的 接口 。 请 求 一 个 资源 的 过 程 可 以 理解 为 ， 访 问 一 个 具有 指定 性 和 描 
述 性 的 URI， 经 由 HTTP， 将 资源 的 表述 从 服务 器 转移 到 客户 端 ， 或 者 相反 方向 。 


REST 不 是 一 种 技术 (technology) ， 也 不 是 一 个 标准 (standard) 或 协议 (protocol) ， 它 使 用 既 有 标准 : HTTP+URI+XML 四， 来 实现 其 要 求 的 架构 风格 。 因 此 ， 与 之 对 应 的 不 是 SOAP， 而 是 像 
RPC 这 样 的 架构 风格 。 


1.1.2 ”基本 实现 形式 


HTTP+URI+XML 是 REST 的 基本 实现 形式 ， 但 不 是 唯一 的 实现 形式 。REST 从 推出 时 就 使 用 已 有 的 HTTP 协 议 、URI 协 议 来 描述 ， 而 对 如 何 使 用 一 种 编程 语言 来 实现 ， 并 没有 进行 任何 描述 和 规定 ， 甚 至 对 
于 REST 应 该 包含 哪些 传输 类 型 或 者 数据 格式 也 没有 描述 ， 但 通常 的 实现 至 少 包含 XML 格式 。 具 体 而 言 ，HTTP 协 议和 URI 用 于 统一 接口 和 定位 资源 ， 文 本 、 二 进 制 流 、XML 和 JSON 等 格式 用 来 作为 资源 的 表 
述 。 正 如 采用 已 有 技术 XMLHttpRequest+JavaScript+XML (XML 后 来 几乎 被 JSON 蔡 代 ) 实现 AJAX 一 样 ， 使 用 HTTP+URI+XML 实 现 REST 的 好 处 是 让 开发 者 持 有 这 些 已 知 的 技术 来 开发 REST， 人 入门 门槛 
较 低 ， 关 注 点 更 容易 放 到 REST 的 核心 概念 和 业务 逻辑 上 。 


这 里 要 提示 读者 的 是 ， 以 HTTP+URI+XML 实 现 的 应 用 并 不 一 定 是 REST 式 的 ， 但 对 于 AJAX， 这 个 逆 命 题 (以 XMLHttpRequest+JavaScript+XML 实 现 的 应 用 一 定 是 AJAX 应 用 ) 是 成 立 的 。 因 为 AJAX 是 
一 种 “技术 流派 ”， 而 REST 是 一 种 架构 风格 。 学 习 和 使 用 REST 的 关键 是 掌握 这 种 思想 ， 而 不 是 具体 的 实现 形式 。 


四 该 论文 的 中 文 版 译 于 2007 年 ， 中 文 名 为 《架构 风格 与 基于 网 络 的 软件 架构 设计 》， 此 后 再 次 修订 ， 名 为 《架构 风格 与 基于 网 络 应 用 软件 的 架构 设计 (中文 修订 版 ) 》， 详 见 本 书 的 参考 资料 。 
思 ] XML 似乎 成 为 了 数据 格式 的 借 指 ， 不 仅 代表 又 ML 本 身 。 


1.2 ”解读 REST 服 务 


英文 RESTful 对 应 的 中 文 是 REST 式 的 。RESTful 的 应 用 或 者 Web 服 务 是 常见 的 两 种 REST 式 的 项 目 部 署 、 存 在 的 方式 。 本 节 将 介绍 RESTful Web services 并 对 比 和 传统 Web Services 的 不 同 。 


1.REST 式 的 Web 服 务 


RESTful Web Services (REST 式 的 Web 服 务 ) 是 一 种 遵守 REST 式 风格 的 Web 服 务 。 REST 式 的 Web 服 务 是 一 种 ROA (Resource-Oriented Architecture， 面 向 资源 的 架构 ) 的 应 用 。 其 主要 特点 是 方 
法 信息 存在 于 HTTP 的 方法 中 (比如 GET、PUT) ， 作 用 域 存在 于 URI 中 。 例 如 ， 在 一 个 获取 设备 资源 列表 的 GET 请 求 中 ， 方 法 信息 是 GET， 作 用 域 信息 是 URI 中 包含 的 对 设备 资源 的 过 滤 、 分 页 和 排序 等 条 
件 。 


2. 对 比 RPC 风 格 


相 比 Web 服 务 领域 广 为 流 行 的 RPC (Remote Procedure Call， 远 程 过 程 调用 ) 风格 ，REST 风 格 更 轻 量 和 快速 。 从 方法 信息 角度 看 ，REST 采 用 标准 的 HTTP 方 法 ， 而 RPC 请 求 都 是 HTTP 协 议 的 POST 方 


法 ， 其 方法 信息 包含 在 SOAP 协 议 包 或 HTTP 协 议 包 中 ， 方 法 名 称 不 具有 通用 性 。 从 作用 域 角度 看 ，REST 采 用 URI 显 式 定义 作用 域 ， 而 RPC 的 这 一 信息 同样 包含 于 协议 包 中 ， 不 能 直观 呈现 。 


RPC 风 格 的 开发 关注 于 服务 器 -客户 端 之 间 的 方法 调用 ， 而 不 关注 基于 哪个 网 络 层 的 哪 种 协议 。 也 就 是 说 ，RPC 是 面向 方法 调用 过 程 的 ， 相 比 而 言 ，REST 是 面向 资源 状态 的 。RPC 风 格 的 两 个 代表 是 
XML-RPC 和 大 Web 服 务 。 


(1) XML-RPC 


XML-RPC 是 一 种 使 用 XML 格 式 封 装 方法 调用 ， 并 使 用 HTTP 协 议 作为 传送 机 制 的 RPC 风 格 的 实现 。XML-RPC 的 请 求 方法 都 是 HTTP 协 议 的 POST 方 法 ， 请 求 和 响应 的 数据 格式 均 为 XML。 


XML-RPC 的 数据 格式 和 使 用 XML 作为 资源 的 表述 的 REST 外 观 上 很 相似 ， 但 数据 的 内 容 则 大 相 径 庭 。REST 式 的 XML 信息 的 主体 是 对 一 个 资源 状态 的 表述 ， 无 须 包 含 方法 信息 ， 因 为 其 请 求 的 HTTP 方 法 
就 已 经 决定 了 这 一 点 。XML-RPC 的 请 求 数据 结构 额外 包含 方法 调用 信息 和 参数 信息 。 


对 于 响应 信息 的 内 容 ， 两 者 也 截然 不 同 ，REST 式 的 通常 会 包含 响应 实体 信息 以 及 HTTP 状 态 码 和 可 选 的 异常 信息 ， 而 XML-RPC 的 返回 信息 仅仅 是 对 方法 调用 的 响应 信息 。 


XML-RPC 是 一 种 遗留 技术 ， 已 经 被 SOAP 取 代 。 在 Java 领 域 ，JAX-RPC 标 准 已 经 被 JAX-WS 取 代 。XML-RPC 的 应 用 依然 存在 ， 著 名 的 测试 用 例 管理 系统 TestLink 的 对 外 接口 就 是 使 用 PHP 开 发 的 XML- 
RPC。 


(2) 大 Web 服 务 


大 Web 服 务 (Big Web Services) 是 Leonard Richardson 和 Sam Ruby 在 其 所 著 的 《RESTful Web Services》 一 书 中 ， 对 基于 SOAP+WSDL+UDDI+WS- 标 准 栈 等 技术 实现 RPC 风 格 的 大 型 Web 服 务 
的 统称 。 事 实 上 ，“ 大 Web 服 务 ” 这 一 说 法 也 被 Java EE 7 的 布道 者 在 多 次 演讲 中 使 用 。 在 java 领域， 对 应 的 标准 主要 是 JAX-WS 2.0/2.1/2.2 (JSR 224) 。 相 较 REST 式 的 Web 服 务 ， 大 Web 服 务 功 能 更 强 
大 、 设 计 更 复杂 。 大 Web 服 务 同样 是 跨 平台 、 跨 语言 的 ， 对 复杂 的 数据 类 型 的 支持 也 非常 好 。 大 Web 服 务 是 基于 RPC 风 格 的 重量 级 的 设计 ， 因 此 方法 和 作用 域 无 法 通过 直观 断定 ， 需 要 定义 在 消息 中 ， 而 且 
方法 名 不 是 统一 和 通用 的 。 同 时 ， 大 Web 服 务 走 HTTP 协 议 时 ， 请 求 都 是 基于 POST 方法 的 。 


对 比 RPC 风 格 的 Web 服 务 ，REST 式 的 Web 服 务 形式 更 简单 、 设 计 更 轻 量 、 实 现 更 快捷 。REST 无 须 引 入 SOAP 消 息 传输 层 ， 无 须 注册 服务 ， 也 没有 客户 端 stub 的 概念 等 。 但 是 ，REST 风 格 的 Web 服 务 并 
没有 像 大 Web 服 务 那样 提供 诸如 安全 策略 等 全 面 的 标准 规范 。 


大 Web 服 务 和 REST 式 的 Web 服 务 各 有 其 优势 ， 并 不 是 一 种 代 换 关 系 。 在 实际 开发 中 ， 两 者 共存 于 一 个 项 目 中 也 是 一 种 解决 方案 。 


3. 对 比 MVC 风 格 


MVC 风 格 的 出 现 将 模型 、 视 图 、 控 制 解 厢 ， 其 亮点 是 从 前 到 后 的 一 致 性 ， 其 结构 简洁 、 风 辑 清晰 ， 易 于 扩展 和 增强 。MVC 在 Java 领 域 的 普遍 实现 方式 是 在 Web 前 端 使 用 标签 库 来 对 应 服务 端的 模型 类 
实例 和 控制 类 实例 ， 标 签 库 和 服务 端 依赖 库 可 以 是 松散 的 耦合 一 一 比如 Spring 生态 系统 ， 也 可 以 是 全 栈 式 的 统一 体系 ， 比 如 JSF 体 系 。 但 无 论 如 何 实现 ， 在 Web 前 端的 开发 过 程 中 ， 必 须 时 刻 考虑 页 面 标签 
和 服务 端的 映射 关系 ， 包 括 模型 类 的 匹配 和 转换 ， 数 据 结构 ， 控 制 类 输入 和 输出 的 参数 类 型 和 数量 等 。 


因此 ，MVC 风 格 偏重 于 解决 服务 器 端的 逻辑 分 层 ， 客 户 端 是 逻辑 分 层 的 延伸 。MVC 的 标签 库 ， 虽 然 其 形态 已 经 和 HTML 页 面 融合 ， 但 本 质 上 还 是 Java 编 写 的 装饰 模式 的 类 实例 ， 对 应 的 是 服务 器 端 使 
Java 编 写 的 模型 类 或 者 控制 器 类 ， 因 此 MVC 很 难 实现 跨 语言 解 厢 。 而 REST 风 格 偏重 于 统一 接口 ， 因 此 具体 实现 就 可 以 跨 平 台 和 跨 语言 。 正 如 附录 中 Web 简 史 中 所 述 ，REST 推 动 了 Web 开 发 的 新 时 代 ， 使 
纯 HTML 作 为 客户 端 ， 没 有 服务 器 端 和 客户 端的 耦合 。 显 而 易 见 ， 使 用 纯 HTML 开 发 的 REST 客 户 端 和 使 用 java 开发 的 REST 服 务 器 端 并 不 存在 语言 上 的 耦合 。 


MVC# 和 和 REST 式 并 不 是 互 斥 的 , 像 Spring 的 MVC 模 块 已 经 支持 REST 式 的 开发 。Jersey 作 为 JAX-RS 标 准 的 实现 ， 也 实现 了 MVC 的 功能 ， 可 参考 相关 模块 : jersey-mvc、jersey-mvc-freemarker 和 
jersey-mvc-jsp。 需 要 说 明 的 是 ， 本 书 致力 于 讲述 JAX-RS， 对 Jersey 实 现 中 的 JAX-RS 之 外 的 功能 只 做 必要 的 讲述 。 由 于 MVC 和 REST 之 间 有 更 多 的 并 行 存在 性 ， 因 此 本 书 余 文 没有 将 MVC 放 入 讲述 之 列 。 


1.3 ”解读 JAX-RS 


JAX-RS 是 Java 领 域 的 REST 式 的 Web 服 务 的 标准 规范 。 如 果 我 们 只 学 习 工 具 的 使 用 而 不 知 标准 是 怎样 定义 的 ， 那 么 可 能 不 会 理解 其 本 质 。 因 此 ， 我 们 首先 来 学 习 和 掌握 JAX-Rs 规 范 ， 这 是 使 用 java 完成 
REST 式 的 Web 服 务 的 基础 和 前 提 。 


1JAX-RS2 标 准 


Java 领 域 中 的 Web Services 是 指 实现 SOAP 协 议 的 JAX-WS。 直 到 Java EE 6 (发 布 于 2008 年 9 月 ) 通过 JCP (Java Community Process) 组 织 定义 的 JSR 311 (http://www.jcp.org/en/jsr/detail? 
id=311) ， 才 将 REST 在 Java 领 域 标准 化 。JSR 311 名 为 The Java APl for RESTful Web Services， 即 JAX-RS， 其 参考 实现 是 GlassFish 项 目 中 的 Jersey 1.0。 此 后 ，JSR 311 进 行 了 一 次 升级 (2009 年 9 
月 ) ， 即 JAX-RS 1.1。JAX-RS 诞 生 后 ， 时 隔 5 年 (2013 年 5 月 ) 发 布 的 Java EE 7 包含 了 JSR 339， 将 JAX-RS 升 级 到 JAX-RS 2.0 (http://www.jcp.org/en/jsr/detail?id=339) 。JAX-RS 2.0 在 前 面 版 本 的 基 
础 上 增加 了 很 多 实用 性 的 功能 ， 比 如 对 REST 客 户 端 API 的 定义 、 异 步 REST 等 ， 对 REST 的 支持 更 加 完善 。 


JAX-RS 的 版 本 对 应 的 参考 实现 的 Jersey 项 目 版 本 信息 参见 表 1-1。 


表 1-1 JAX-RS 标 准 和 Jersey 版 本 信息 


DAXRS 和 JAXRS 员 


2.JAX-RS 2.0 的 目标 


JAX-RS 2.0 标 准 ( 即 JSR 339) 中 定义 了 目标 、 非 目标 和 元 素 等 内 容 。JSR 339 标 准 中 的 这 部 分 内 容 通常 被 以 实现 业务 功能 为 目的 的 开发 人 员 所 忽视 ， 在 此 和 读者 分 享 的 一 个 开发 经 验 是 ， 要 掌握 一 项 技 
术 ， 要 先 掌握 它 背 后 标准 的 定义 。 我 们 首先 来 看 看 JAX-RS 2.0 的 目标 。 


1) 基于 POJO: JAX-RS 2.0 的 API 提 供 一 组 注解 (annotation) 和 相关 的 接口 、 类 ， 并 定义 了 POJO (Plain Ordinary Java Objects) 对 象 的 生命 周期 和 作用 域 。 规 定 使 用 POJO 来 公布 Web 资 源 。 


2) 以 HTTP 为 中 心 : JAX-RS 2.0 采 用 HTTP 协 议 ， 并 提供 清晰 的 HTTP 和 统一 资源 定位 (URI) 元 素来 映射 相关 的 API 类 和 注解 。JAX-RS 2.0 的 API 不 但 支持 通用 的 HTTP 使 用 模式 ， 还 对 WebDAV 和 Atom 
等 扩展 协议 提供 灵活 的 支持 。 


3) 格式 独立 性 : JAX-RS 2.0 对 传输 数据 (HTTP Entity) 的 类 型 /格式 的 支持 非常 宽泛 ， 人 允许 在 标准 风格 之 上 使 用 额外 的 数据 类 型 。 


4) 容器 独立 性 : JAX-RS 2.0 的 应 用 可 以 部 署 在 各 种 Servlet 容 器 中 ， 比 如 Tomcat/Jetty， 也 可 以 部 署 在 支持 JAX-WS 的 容器 中 ， 比 如 GlassFish。 


5) 内 置 于 Java EE: JAX-RS 2.0 是 Java EE 规范 的 一 部 分 ， 它 定义 了 在 一 个 Java EE 容器 内 的 Web 资 源 类 的 内 部 ， 如 何 使 用 Java EE 的 功能 和 组 件 。 


小 白 讲堂 
WebDAV (Web-based Distributed Authoring and Versioning， 基 于 Web 的 分 布 式 创作 和 版 本 控制 ) 是 IETF 组 织 的 RFC 2518 协 议 。WebDAV 基 于 并 扩展 了 HTTP 1.1， 在 HTTP 标 准 方法 以 外 添加 了 : 
* Mkcol: 创建 集合 ; 
“ PropFind/PropPatch: 针对 资源 和 集合 检索 和 设置 属性 ; 
“ Copy/Move: 管理 命名 空间 上 下 文中 的 集合 和 资源 ; 
“Lock/Unlock: 改写 保护 ， 支 持 文件 的 版 本 控制 。 


针对 在 REST 风 格 的 Web 服 务 中 是 否 应 该 使 用 WebDAV， 业 内 的 声音 并 不 一 致 ， 持 反对 意见 的 人 的 主要 观点 是 WebDAV 带 来 了 非 统 一 的 接口 ， 这 违背 了 REST 的 初衷。 本 书 的 示例 将 不 采用 WebDAV， 但 文 
字 部 分 将 讲述 如 何 支持 WebDAV。Atom 类 型 传输 格式 将 在 3.3 节 讲述 。 


3. 非 JAX-RS 2.0 的 目标 


那么 哪些 不 是 JAX-RS 2.0 的 目标 呢 ? 


1) 对 J2SE 6.0 之 前 版 本 的 支持 : JAX-RS 2.0 中 大 量 使 用 了 注解 (annotation) ， 需 要 J2SE 6.0 以 及 更 新 的 版 本 ， 因 此 不 提供 对 J2SE 6.0 以 下 版 本 的 支持 。 


2) 对 服务 的 描述 、 注 册 和 探测 : JAX-RS 2.0 没 有 定义 也 无 须 支持 任何 服务 的 描述 (description) 、 服 务 的 注册 (registration) 和 服务 的 探测 (discovery) 。 


3) HTTP 协 议 栈 : JAX-RS 2.0 没 有 定义 新 的 HTTP 协 议 栈 。 承 载 JAX-RS 2.0 应 用 的 容器 提供 对 HTTP 的 支持 。 


4) 数据 类 型 /格式 类 : JAX-RS 2.0 没 有 定义 处 理 实体 内 容 的 类 ， 它 将 这 一 类 型 的 类 交 由 使 用 JAX-RS 2.0 的 应 用 中 的 类 去 实现 。 


4. 解 读 JAX-RS 元 素 


最 后 ， 我 们 来 看 看 JAX-RS 2.0 中 定义 了 哪些 元 素 。 


1) 资源 类 : 使 用 JAX-RS 注 解 来 实现 相关 Web 资 源 的 Java 类 。 如 果 用 MVC 的 三 层 结构 来 解读 ， 那 么 资源 类 位 于 最 前 端 ， 用 于 接收 请 求 和 返回 响应 。 通 常 但 不 是 约定 使 用 resource 作 为 包 名 ， 三 层 的 包 定 


义 形 如 : resource-service-dao。 


2) 根 资源 类 : 使 用 @Path 注 解 ， 提 供 资 源 类 树 的 根 资源 及 其 子 资源 的 访问 。 资 源 类 分 为 根 资源 类 和 子 资源 类 。 由 于 Jersey 默 认 提供 WADL (参见 2.4 节 ) ， 因 此 每 个 应 用 公布 的 全 部 资源 接口 可 以 通过 
WADL 页 面 查阅 。 


3) 请 求 方法 标识 符 : 使 用 运行 期 注解 @HttpMethod， 用 来 标识 处 理 资源 的 HTTP 请 求 方法 。 该 方法 将 被 资源 类 的 相应 方法 处 理 ， 标 准 的 方法 包括 DELETE、GET、HEAD、OPTIONS、POST、PUT， 
详 见 3.1 节 。 


4) 资源 方法 : 资源 类 中 定义 的 方法 ， 使 用 了 请 求 方法 标识 符 ， 用 来 处 理 相关 资源 的 请 求 。 就 是 上 面 提 到 的 资源 类 的 相应 方法 。 


5) 子 资源 标识 符 : 资源 类 中 定义 的 方法 ， 用 来 定位 相关 资源 的 子 资源 。 


6) 子 资源 方法 : 资源 类 中 定义 的 方法 ， 用 来 处 理 相关 资源 的 子 资源 的 请 求 。 


7) Providers: 一 种 JAX-RS 扩 展 接口 的 实现 类 ， 扩 展 了 JAX-RS 运 行 期 的 能 力 。 第 4 章 详 述 了 各 种 Providers 及 其 实现 。 


8) Filter: 一 种 用 于 过 滤 请 求 和 响应 的 Provider， 详 见 4.4 节 。 


AD 


Entity Interceptor: 一 种 用 于 处 理 拦截 消息 读 写 的 Provider。 


10) Invocation: 一 种 用 于 配置 发 布 HTTP 请 求 的 客户 端 API 对 象 ， 详 见 5.1.3 节 。 


11) WebTarget: 一 种 使 用 URI 标 识 的 Invocation 容 器 对 象 ， 详 见 5.1 节 。 


12) Link: 一 种 携带 元 数据 的 URI， 包 括 媒体 类 型 、 关 系 和 标题 等 ， 详 见 3.4 节 。 


1.4 _ Jersey 项 目 概要 


Jersey 是 JAX-RS 标 准 的 参考 实现 ， 是 Java 领 域 中 开发 REST 式 的 Web 服 务 的 “正统 ”工具 。 这 样 讲述 的 目的 是 避免 读者 混淆 REST 领 域 诸多 工具 的 地 位 ， 并 无 偏好 推荐 之 意 。 本 节 将 带领 读者 走 进 Jersey 
的 世界 。 


Jersey 项 目 是 GlassFish 项 目的 一 个 子 项 目 ， 专 门 用 来 实现 JAX-RS (JSR 311 和 JSR 339) 标准 ， 并 提供 了 扩展 特性 。 


1. 获 得 Jersey 


Jersey 项 目的 网 址 是 https://jersey.java.net， 这 是 Jersey 的 官方 网 站 。 该 网 站 同时 提供 了 JAX-RS 和 JAX-RS 2.0 两 个 并 行 版 本 ,分别 是 Jersey 1.1 (截至 本 书 发 稿 ， 最 新 版 本 是 Jersey 1.18) 和 Jersey 
2.0 (截至 本 书 发 稿 ， 最 新 版 本 是 Jersey 2.9) 。 读 者 可 以 通过 单 击 “latest Jersey User Guide” 获 取 和 阅读 最 新 版 本 的 用 户 手册 ， 这 是 官方 发 布 的 第 一 手 的 参考 资料 。 


Jersey 项 目的 下 载 地 址 https://jersey.java.net/download.html，Jersey 项 目 使 用 Maven 管 理 项 目 ， 该 页 面 至 上 而 下 分 别 是 : 


“ JAX-RS 标 准 列表 链接 。 


“Jersey 最 新 参考 实现 的 jar 包 下 载 。 

“ Jersey 最 新 参考 实现 的 示例 代码 下 载 。 

“ 创建 基于 Maven 管 理 的 JAX-RS 容 器 Jersey 应 用 。 
“ 创建 基于 Maven 管 理 的 Servlet 容 器 Jersey 应 用 。 


"JAX-RS 1.1 的 参考 实现 包 下 载 。 


2.Jersey 源 代码 


Jersey 2 使 用 GitHub 管 理 源 代码 ，GitHub 的 客户 端 非常 简洁 。 单 击 首页 下 方 的 “Source Control” 进 入 https://jerseyjava.net/scm.html 页 面 ， 该 页 面 提供 了 如 何 使 用 GIT 来 克隆 Jersey 的 源 代码 的 介 
绍 。Jersey 源 代码 的 托管 地 址 是 https://github.com/jersey/jersey ( 见 图 1-1) 。 


如 图 1-1 所 示 ，Jersey 项 目的 源 代码 是 使 用 Maven 构 建 的 多 模块 项 目 。 每 个 目录 代表 一 个 模块 ， 比 如 core-server 目 录 就 是 Jersey 的 Server 模 块 。bom 目录 是 个 特殊 的 目录 ， 是 Maven 的 元 数据 目录 ， 用 
于 多 模块 Maven 项 目的 组 织 和 定义 。 通 过 浏览 该 页 面 可 以 观察 到 Jersey 框 架 的 模块 ， 本 章 随后 会 介绍 Jersey 的 各 个 模块 。 第 2 章 将 对 基于 Maven 管 理 的 Jersey 应 用 做 详细 的 讲述 和 演示 。 
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This is an active mirror of Jersey 2.x workspace from http://jersey.java.net. Any changes made here are 
automatically propagated to java.net and vice versa. Forks and pull requests are welcomel http-/Wierseyjava.net ¢> Code 
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[= 
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[maven-release-plugin] prepare for next development teration 3 Eu Graphs 
入 shamoh authored 4 days ago latast comrit a71ife9o264 廊 » Network 


a archetypes [maven-release-plugin] prepare for next development iteration 4days ago 


面 bom [maven-release-plugin] prepare for next development iteration 4days ago HTTPS cbne URL 


https://github -col| 良 


You can clone with HTTPS, SSH, 


a bundles [maven-release-plugin] prepare for next development iteration 4days ago 
面 connectors [maven-release-plugin] prepare for next development iteration 4days ago or Subversion © 


可 containers [maven-release-plugin] prepare for next development iteration 4 days ago Clone in Desktop 


面 core-ciient [maven-release-plugin] prepare for next development iteration 4 days ago ® Download ZIP 


可 core-common [maven-release-plugin] prepare for next development iteration 4days ago 


core-server [maven-release-plugin] prepare for next development iteration 4 days ago 


面 docs [maven-release-plugin] prepare for next development iteration 4 days ago 


图 1-1 Jersey 源 代码 仓库 


小 白 讲 堂 


Maven (http://maven.apache.org/) 是 Apache 开 源 组 织 的 项 目 ， 该 项 目 用 于 构建 和 组 织 Java 的 项 目 。 读 者 如 果 对 Maven 不 熟悉 ， 推 荐 阅读 许 晓 试 (Juven Xu) 所 著 的 《Maven 实 战 》【〔 机 械 工 业 出 版 社 出 
版 ) 。 


如 果 读者 对 命令 行 不 熟悉 或 者 没有 兴趣 ， 可 以 使 用 GUI 工具 来 完成 源 代 码 的 管理 。 对 于 托管 在 GitHub 的 项 目 ， 可 以 使 用 GitHub 官 方 提供 的 客户 端 来 管理 源 代 码 ，Windows 版 本 下 载 地 址 : 
http://windows.github.com，Mac 版 本 下 载 地 址 : http://mac.github.com。 这 款 工具 的 使 用 非常 简单 ， 如 图 1-2 所 示 ， 左 侧 树 包 括 本 地 仓库 和 GitHub 远 程 仓库 两 个 结 点 。 右 侧 是 仓库 列表 ， 示 意图 中 包 
括 本 书 的 示例 项 目 jax-rs2-guide、 第 11 章 示例 项 目 jax-rs2-atup 和 Jersey 源 代码 等 仓库 。 需 要 指出 的 是 ， 其 处 理 版 本 冲突 的 能 力 不 足 ， 需 要 借助 命令 行 来 完成 。 


小 白 讲 堂 


GIT 是 一 种 开源 的 分 布 式 SCM (Source Code Management， 源 代码 管理 ) 工具 ， 下 载 地 址 为 http://git-scm.com/download。 读 者 如 果 对 GIT 不 熟悉 ， 推 荐 阅读 蒋 侈 所 著 的 《Git 权 威 指 南 》 (机 械 工业 出 版 社 
出 版 )。 


GitHub 是 GIT 服 务 器 中 比较 知名 和 成 功 的 ， 它 提供 了 基于 身份 认证 的 项 目 托管 等 功能 。 时 下 非常 多 的 知名 开源 软件 都 将 版 本 控制 迁移 到 GIT 并 使 用 GitHub 托 管 。 如 果 可 以 ， 希 望 读者 能 从 
https://help.github.com/ 中 得 到 更 多 信息 。 


+ create 


local Filter Repositories 


DD feuyews/ix rs2-atup 


© feuyeux/jax-rs2-guide 


只 jersey/jersey 
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中 feuyeux/jsfrfcc 


只 feuyeux/kms 


图 1-2” GitHub 客户 端 示意 图 


3.Jersey 问 答 


StackOverflow 是 专业 的 程序 员 问 答 系统 ，Jersey 提 供 了 其 问题 列表 地 址 : http://stackoverflow.com/questions/tagged/jersey。 从 中 可 以 看 出 开源 社区 对 问答 系统 的 重视 。 另 外 ， 邮 件 列 表 也 是 一 种 
知识 共享 的 途径 ， 读 者 可 以 自行 订阅 ， 地 址 是 : https://jersey.java.net/mailing.html。 


实践 趣事 ”这 里 想 和 读者 分 享 的 是 ， 一 名 不 断 成 长 的 程序 员 中 一 定 是 勤奋 和 富有 热情 的 ， 这 是 开源 社区 和 StackOverftlow 这 样 的 问答 系统 的 生存 基石 。 社 区 和 个 人 的 成 长 是 相辅相成 的 。 推 荐 读者 在 遇 到 
问题 时 ， 第 一 个 想到 的 是 搜 Google、 搜 StackOverflow ， 而 不 是 张嘴 就 间 ， 问 周边 的 人 应 该 是 正确 做 法 中 最 后 的 办 法 。 顺 便 要 说 的 是 ， 英 语 是 程序 员 绕 不 开 的 技能 ， 一 起 加 油 吧 ! 


4.Jersey 项 目 管理 


Jersey 使 用 JIRA 作 为 项 目 管理 平台 ， 地 址 是 https://java.net/jira/browse/JERSEY。JIRA 和 StackOverflow 不 同 的 是 ， 这 个 平台 是 Jersey 团 队 日 常 开发 的 管理 平台 ， 也 就 是 说 ， 这 是 Jersey 官 方 的 缺陷 管 
理 平台 ， 用 于 上 报 缺陷 和 改进 意见 ， 而 不 是 社区 性 质 的 交流 平台 。 我 们 可 以 从 中 了 解 到 Jersey 项 目的 进展 情况 。Jersey 是 一 个 非常 活跃 的 项 目 ， 不 仅 可 以 从 GitHub 的 源 代码 的 提交 活动 中 看 到 该 项 目 频繁 的 
更 新 ， 在 RA 中， 也 可 以 看 到 该 项 目 推进 的 速度 。 


宅 人 坑 事 


这 里 为 喜欢 开源 社区 活动 的 读者 举 个 例子 。 我 在 撰写 本 书 的 开始 ，Jersey 2.0 并 不 支持 与 Spring 的 集成 ， 因 为 Jersey 的 IoC 容 器 由 GlassFish 的 另 一 个 子 项 目 HK2 来 支持 。 随 后 ， 我 在 JIRA 上 发 现 一 个 Jersey 2.x 
支持 与 Spring 集成 的 任务 被 创建 了 (https:/VjavaneUjira/browse/JERSEY-1957) ， 此 后 我 经 常 观察 其 进展 状态 ， 最 终 看 到 了 这 个 功能 在 Jersey 2.2 中 以 扩展 包 的 形式 发 布 了 。 因 此 ， 当 使 用 Jersey 时 ， 如 果 遇 到 
Jersey 本 身 的 问题 ， 可 以 跟踪 Jersey 的 JIRA 平 台 来 查看 Bug 的 修复 状态 ， 包 括 将 在 哪个 版 本 修复 ， 有 什么 样 的 临时 解决 办 法 (workaround) 。 同 时 ， 跟 踪 JIRA 也 可 以 了 解 新 版 本 的 发 布 情况 ， 包 括 新 增 哪些 功 
能 ， 升 级 给 哪 一 部 分 带 来 性 能 、 安 全 的 提升 等 。 换 句 话说 ,JIRA 展 示 了 Jersey 项 目的 缺陷 修复 和 新 功能 发 版 的 计划 (roadmap) 。 


5.Jersey 许 可 


开发 者 使 用 开源 软件 的 前 提 是 了 解 它 的 许可 证 版 本 ， 否 则 可 能 会 带 来 侵权 问题 。 相 信 在 正规 的 公司 ， 大 家 都 有 被 开发 管理 部 门 的 人 “恐吓 ”的 经 历 。 开 发 者 需 感谢 开发 管理 部 门 所 做 的 工作 ， 他 们 为 公 
司 规避 了 商业 侵权 的 风险 ， 因 为 引用 的 源 代码 如 果 出 自 “ 传 染 性 ”许可 ， 该 项 目 是 不 能 用 于 闭 源 的 商业 用 途 的 。 


Jersey 的 许可 证 说 明 地 址 是 : https:Wijerseyjava.net/license.html。 从 中 我 们 可 以 了 解 到 Jersey 使 用 的 是 双 许可 证 : CDDL (Common Development and Distribution License， 开 源 通用 开发 和 分 发 
许可 证 ) 1.1 和 GPLv2 (类 路 径 例外 ) 许可 证 。 双 重 许可 是 依照 两 套 (或 更 多 套 ) 不 同 的 条 款 和 条 件 分 发 相同 软件 的 做 法 。 在 为 软件 授予 双重 许可 时 ， 接 收入 可 以 选择 他 们 希望 依照 哪 种 条 款 获 得 软件 。 使 用 
双重 许可 的 两 个 常见 动机 是 遵循 商业 模式 和 保持 许可 证 兼容 性 。GPLv2.0 许 可 证 为 无 法 依照 CDDL 许 可 证 使 用 Jersey 的 供应 商 提 供 了 一 个 额外 选项 。Jersey 许 可 证 使 整套 产品 和 包 保持 一 致 (GlassFish 项 目 同 
样 依照 CDDL 和 GPLv2 (类 路 径 例外 ) 授予 双重 许可 ) 。 


6.Jersey 的 模块 


Jersey 框 架 是 由 核心 模块 、 容 器 模块 、 连 接 器 模块 、Media 模 块 、 扩 展 模 块 、 测 试 框架 模块 和 GlassFish Bundle 模 块 7 个 大 的 模块 组 成 。 这 不 是 一 成 不 变 的 ， 随 着 Jersey 的 不 断 发 展 和 完善 ， 会 有 新 的 模 
块 加 入 进来 。 推 荐 读者 浏览 官方 文档 ， 最 新 版 本 的 地 址 为 : https://jersey.java.net/documentation/latest/modules-and-dependencies.html， 从 而 获得 最 新 的 信息 。 


小 白 讲 堂 


类 路 径 例 外 是 由 自由 软件 基金 会 的 GNU/ 类 路 径 项 目 制定 的 。 它 允许 用 户 将 依照 任何 许可 证 提供 的 应 用 程序 链接 到 依照 GPLv2 许 可 的 软件 中 包含 的 库 ， 而 该 应 用 程序 不 受 GPL 要 求 公开 其 本 身 的 限制 。 为 
什么 需要 使 用 类 路 径 例外 ? 因为 作为 “基于 [GPH 程 序 的 作品 ”的 一 部 分 提供 的 所 有 代码 还 应 获得 GPL 许可 。 因 此 ， 需 要 指定 GPL 许可 证 例外 情况 ， 以 便 明 确 将 链接 到 GPL 实现 的 任何 应 用 程序 从 该 许可 要 求 
中 排除 。 类 路 径 例 外 实现 了 这 一 目的 。 


(1) 核心 模块 


Jersey 核 心 模块 由 通用 包 、 服 务 器 实现 和 客户 端 实现 3 个 子 模块 组 成 ， 是 使 用 Jersey 必 需 的 依赖 ， 见 表 1-2。 


表 1-2 Jersey 核 心 模块 列表 


模块 名 称 模块 说 明 源 代码 相对 目录 


jersey-client Jersey 核心 客户 端 实现 core-client 


jersey-common Jersey 通用 包 core-common 
jersey-server Jersey 核心 服务 器 实现 core-server 


(2) 容器 模块 


Jersey 提 供 了 3 种 对 应 于 外 部 容器 的 HTTP 容 器 ， 分 别 是 Grizzly 2、JDK-HTTP 和 SIMPLE-HTTP，Grizzly 2 同时 提供 了 Servlet 容 器 。 对 于 Servlet 的 实现 ，Jersey 提 供 了 对 Servlet 2.x 和 Servlet 3.x 两 个 版 
本 的 实现 。 它 们 对 应 的 包 名 见 表 1-3， 详 情 可 参考 第 2 章 。 


表 1-3 Jersey 容器 模块 列表 


模块 名 称 源 代码 相对 目录 
Jersey-container-grizzly2-http containers/grizzly2-http 
Jersey-container-grizzly2-servlet Grizzly 2 版 Servlet 容 髓 containers/ grizzly2-servlet 
jersey-container-jdk-http containers/ Jdk-http 
Jersey-container-servlet containers/ jersey-servlet 
Jersey-container-servlet-core containers/ jersey-servlet-core 
Jersey-container-simple-http containers/simple-http 


(3) 连接 器 模块 


Jersey 客 户 端 底层 依赖 连接 器 实现 网 络 通信 ， 如 果 标 准 的 客户 端 模块 无 法 实现 功能 需求 ， 可 以 考虑 引入 Grizzly 连 接 器 或 者 Apache 连 接 器 ， 见 表 1-4， 详 情 可 参考 第 5 章 。 
表 1-4 Jersey 连接 器 模块 列表 


模块 名 称 模块 说 明 源 代码 相对 目录 


Jersey-grizzly-connector Jersey 客户 端 Grizzly 连接 带 connectors/grizzly-connector 
Jersey-apache-connector Jersey 客户 端 Apache 连接 融 connectors/apache-connector 


(4) Media 模 块 


Jersey Media 模 块 是 支持 Jersey 处 理 传输 数据 媒体 类 型 的 模块 。 该 模块 提供 了 4 种 处 理 JSON 的 方式 ,分 别 是 Jackson、Jettison、MOXy 和 JSON-P。 另 外 ，Multipart 包 用 于 对 Form 表 单 的 支持 ，SSE 
于 对 Server Sent Events 支 持 ， 见 表 1-5， 详 情 可 参考 第 3 章 。 


(5) 扩展 模块 


Jersey 生 态 环境 中 包含 了 许多 JAX-RS 2.0 标 准 之 外 的 功能 ， 比 如 MVC、Bean 验 证 等 辅助 REST 实 现 的 模块 ， 还 有 像 Spring 支 持 包 这 样 的 对 第 三 方 框架 支持 的 模块 见 表 1-6。 


表 1-5 Jersey Media 模 块 列表 


模块 名 称 源 代码 相对 目录 
jersey-media-jSon-jackson media/json-jackson 
jersey-media-json-jettison media/json-jettison 
Jersey-media-json-processing media/json-processing 
Jersey-media-moxy media/moxy 
Jersey-media-multipart media/multipart 


Jersey-media-sse Jersey Server Sent Events 支持 包 media/sse 


表 1-6 Jersey 扩 展 模 块 列表 


模块 名 称 源 代码 相对 目录 
jersey-bean-validation ext/bean-validation 
jersey-mvc-freemarker Freemarker 模板 支持 包 ext/mvc-freemarker 
jersey-mve-jsp extmve-jsp 
Jersey-proxy-client ext/proxy-client 


兼容 Jersey 1.x 和 Jersey 2.x 的 Servlet 


Jersey-servlet-portability ext/servlet-portability 


容 咒 支持 包 
Jersey-wadl-doclet Javadoc 支持 包 ext/wadl-doclet 
Jersey-spring3 Spring 3 支持 包 ext/spring3 


(6) 测试 框架 模块 


Jersey 提 供 了 非常 易 用 且 功 能 强大 的 测试 框架 ， 见 表 1-7。 测 试 框架 提供 了 测试 过 程 中 完整 的 服务 器 端 和 客户 端 功 能 ， 通 过 测试 框架 ， 开 发 者 可 以 减少 很 多 模板 代码 的 编写 。 详 情 可 参考 7.1 节 。 


表 1-7 Jersey 测 试 框架 模块 列表 


模块 名 称 模块 说 明 源 代码 相对 目录 


jersey-test-framework-core Jersey 核心 测试 框架 test-framework /core 
Jersey-test-framework-provider-bundle test-framework/providers/bundle 
Jersey-test-framework-provider-default-client 测试 框架 客户 端 包 test-framework/providers/default-client 
jersey-test-framework-provider-external 测试 框架 扩展 容器 test-framework/providers/external 
Jersey-test-framework-provider-grizzly2 测试 框架 Grizzly 2 容 带 test-framework/providers/grizzly2 

( 续 ) 

模块 名 称 源 代码 相对 目录 

jersey-test-framework-provider-inmemory 测试 框架 内 存 容 器 test-framework/providers/inmemory 
jersey-test-framework-provider-jdk-http 测试 框架 JDK 版 HTTP 容器 | test-framework/providers/jdk-http 
jersey-test-framework-provider-simple 测试 框架 简单 版 HTTP 容器 | test-framework/providers/simple 


(7) GlassFish Bundle 模 块 


GlassFish Bundle 模 块 是 Jersey 提 供 的 用 于 以 Bundle 方 式 支持 GlassFish 服 务 器 的 模块 ， 包 括 CDI 和 EJB 集 成 的 扩展 包 ， 见 表 1-8。 


表 1-8 GlassFish Bundle 模 块 列 表 


模块 名 称 模块 说 明 源 代 码 相 对 目录 
jersey-gf-cdi Jersey 集成 GlassFish 的 CDI 包 containers\glassfish\jersey-gf-cdi 
Jersey-gf-ejb Jersey 集成 GlassFish 的 EJB 包 containers\glassfish\jersey-gf-ejb 


宅 人 坑 事 


Jersey 在 2.6 版 本 做 了 一 次 包 重 构 ， 清 除了 对 Guava 和 ASM 的 自然 依赖 。 如 果 读 者 的 项 目 需要 做 Jersey 版 本 迁移 ， 需 要 注意 这 一 点 。 新 的 包 名 为 : jersey.tepackaged.com.google.common 和 


jersey.repackaged.objectweb.asm。 


7.GlassFish 项 目 


GlassFish 项 目地 址 为 https://glassfish.java.net。GlassFish 比 较 著名 的 是 Java EE 服务 器 项 目 Oracle GlassFish Server， 该 项 目 还 同时 包含 Java EE 中 包含 的 一 系列 标准 规范 的 参考 实现 ， 这 些 参 考 实现 
集成 于 GlassFish Server， 为 其 Java EE 容器 提供 支持 。 其 中 对 JAX-RS 2.0 的 实现 项 目 是 Jersey。 


为 什么 要 在 JAX-RS 2.0 的 介绍 中 提 及 GlassFish 项 目 集 呢 ? 因 为 Jersey 处 于 GlassFish 生 态 环境 中 ，GlassFish 又 是 Java EE 生态 环境 的 实现 描述 。 举 个 例子 ， 当 你 需要 在 REST 项 目 中 访问 数据 库 时 ， 也 许 出 
于 首选 基于 标准 的 实现 的 考虑 ， 你 会 选择 使 用 PA。 而 JPA 的 参考 实现 EclipseLink 就 是 GlassFish 项 目 集 的 成 员 。 这 就 像 在 你 观赏 深海 的 一 条 鱼 的 时 候 ， 势 必 有 兴趣 了 解 它 会 以 哪些 生物 为 生 ， 又 为 哪些 生 
提供 了 生存 保障 。 通 过 了 解 GlassFish 项 目 ， 可 以 更 好 地 完成 REST 式 的 Web 服 务 。 尤 其 ， 当 你 用 户 用 NetBeans 作 为 开发 工具 时 ，GlassFish 服 务 器 和 GlassFish 项 目 集 是 你 生产 中 的 “日 用 消费 品 ”。 


这 里 所 列 的 项 目 是 除 Jersey 以 外 其 他 的 GlassFish 项 目 ， 排 列 顺序 并 不 严谨 ， 大 体 上 以 其 与 Jersey 的 紧密 关系 降序 排列 。 


(1) HK2 


HK2 项 目地 址 为 http://hk2.java.net。HK2 是 轻 量 级 DI 架构 ， 实 现 loC 和 DI 的 内 核 ， 是 Jersey 实 现 容器 内 管理 Bean 的 基础 ， 见 表 1-9。 


(2) Grizzly 


Grizzly 的 项 目地 址 为 https://grizzly.java.net。Grizzly 是 一 个 异步 /OQ 的、 高 效 而 健壮 的 服务 器 ， 可 以 用 作 HTTP 服 务 器 、Servlet 容 器 ， 支 持 AJP、Comet、WebSocket， 以 及 相对 于 RESTFuI 的 另 一 种 
Web Service 实 现 JAX-WS， 见 表 1-10。 


如 何 使 用 和 配置 Grizzly 依 赖 于 用 户 的 需求 ， 也 就 是 说 ， 用 户 的 项 目 不 必 加 载 Grizzly 提 供 的 全 部 jar 包 。 表 1-11 列 出 了 Grizzly 项 目的 各 个 模块 信息 ， 可 以 参考 该 表 定义 用 户 的 项 目 对 Grizzly 的 依赖 。 


表 1-9 HK2 项 目 情况 简 表 


项 目 名 称 JSR 编号 JSR 名 称 当前 版 本 
HK2 JSR-330 22 


表 1-10 ”Grizzly 项 目 情况 简 表 


项 目 名 称 中 文 直译 JSR 编号 JSR 名 称 当前 版 本 
Grizzly JSR-356 Java API for WebSocket 233 


表 1-11 ”Grizzly 模 块 列表 


模块 名 称 描述 
grizzly-framework Grizzly 核心 包 
grizzly-http-server HTTP 服务 器 包 
grizzly-http-servlet Servlet 容器 包 
grizzly-portunif Port Unification 包 ， 支 持 多 种 协议 和 端口 的 协同 工作 
grizzly-comet Comet 包 ， 支 持 Comet 方式 的 BS 访问 。 典 型 的 场景 是 长 轮 询 
grizzly-WebSockets WebSockets 包 ， 支 持 WebSocket 协议 (RFC 6455 )， 可 以 和 HTMLS5 协同 工作 


A 卫 包 ， 支 持 A 卫 协议 。A 卫 是 一 种 使 Web 服务 器 和 应 用 服务 器 通信 的 协议 ， 
典型 的 应 用 是 Apache 和 Tomcat 的 通信 
grizzly-http-server-jaxws 支持 JAX-WS 标准 的 HTTP 服务 需 包 


grizzly-http-ajp 


(3) EclipseLink 


EclipseLink 项 目地 址 为 http://www.eclipse.org/eclipselink。EclipseLink 是 JPA 2.1 的 一 个 实现 ， 同 时 它 还 实现 了 其 他 的 JSR 作 为 扩展 。JPA 2.1 是 Java EE 7 的 成 员 ， 是 对 JSR 317 (JPA 2.0) 的 升级 。 
在 JPA 2.1 的 实现 中 ， 最 常用 的 是 JBoss 的 Hibernate， 该 项 目 从 4.3 版 本 开始 实现 JPA 2.1。 也 就 是 说 ，Hibernate 4.2 是 JPA 2.0 的 最 后 一 个 版 本 。 读 者 在 开发 的 时 候 要 注意 依赖 项 目 版 本 对 标准 的 支持 。 
EclipseLink 项 目 情 况 见 表 1-12。 


表 1-12 EclipseLink 项 目 情况 简 表 


JPA 标 准 还 有 其 他 的 实现 ， 可 参考 http://en.wikipedia.org/wiki/Java_Persistence_API。 


当前 版 本 


EclipseLink 


(4) Metro 


Metro 项 目地 址 为 https://metro.java.net。Metro 是 JSR 中 多 个 标准 的 官方 实现 集 ， 目 的 是 实现 全 栈 式 的 Web Service。 Metro 项 目 情况 见 表 1-13。 


表 1-13 ” Metro 项 目 情况 简 表 


Metro pA 


Metro 项 目 中 的 多 个 标准 的 作用 各 有 不 同 。 


“ JAX-WS 标 准 结合 了 XMIL-RPC 使 用 SOAP 协 议 来 实现 Web Service。JAX-WS 实 现 中 ， 不 可 不 提 的 另外 两 个 实现 分 别 是 Apache 的 CXF 和 Axis。 


:WSIT 的 前 身 是 Tango， 是 一 种 JAX-WS 和 .NET 互 操作 的 技术 ， 实 现 了 WS+ 标 准 。 


: SAAJ 规 范 的 作用 是 基于 SOAP 协 议 XML 格式 传递 带 附 件 的 SOAP 消 息 。 


“ JAXP 标 准 涵盖 了 Java 对 XML 过 程式 处 理 的 诸多 技术 ， 包 括 DOM、SAX 和 StAX， 同 时 该 标准 定义 了 解读 XML 样式 的 XSLT。 


'“JAXB 标 准 是 Java 处 理 XML 和 POJO 映 射 的 技术 ， 是 Jersey 中 处 理 传输 数据 的 重要 依赖 。 


(5) Open MQ 


Open MQ 项 目地 址 为 https://mq.java.net。Open MQ 是 JMS 2.0 的 参考 实现 。JSR 343 是 Java EE 7 的 成 员 ， 虽 在 简化 JMS 的 API。 关 于 消息 队列 的 实现 数量 ,恐怕 是 其 他 任何 一 个 标准 都 望尘莫及 的 。 
几乎 每 一 个 有 能 力 开发 服务 器 软件 、 中 间 件 的 公司 都 有 自己 的 MQ， 可 参考 http://en.wikipedia.org/wiki/Message_queue。 目 前 支持 JMS 2.0 的 其 他 实现 并 不 多 ，HornetQ 2.4.0+ 兼 容 JMS 1.1 和 JMS 2.0 
是 为 数 不 多 的 JMS 2.0 的 其 他 实现 。Open MQ 简介 见 表 1-14。 


表 1-14 Open MQ 项 目 情况 简 表 


项 目 名 称 JSR 编号 JSR 名 称 当前 版 本 
Open Message Queue “| 。 开源 消息 队列 50 


(6) Mojarra 


Mojarra 项 目地 址 为 https://Java SErverfaces.java.net。Mojarra 是 JSF 2 的 官方 实现 。JSF 是 一 种 全 栈 式 的 、 事 件 驱动 的 B/S 开 发 模式 框架 ， 它 包括 浏览 器 端的 丰富 组 件 ， 服 务 器 端 覆盖 Java EE 的 各 种 特 
性 ， 见 表 1-15。JSF 相 对 于 Spring， 借 鉴 了 其 核心 思想 loC 和 AOP， 同 时 给 出 了 标准 规范 。 这 有 点 类 似 JPA 借 鉴 了 Hibernate 的 O/R Mapping 思 想 并 标准 化 。 


JSF 的 另 一 个 实现 是 Apache 的 MyFaces， 当 前 版 本 为 2.0.18。 另 外 ，JBoss 的 RichFaces 是 基于 JSF 的 扩展 中 最 为 完善 和 常用 的 。 更 多 有 关 JSF 的 内 容 和 原理 ， 可 参考 笔者 的 《JSF 2 和 RichFaces 4 使 用 指 
南 》。 


表 1-15 Mojarra 项 目 情况 简 表 


EEE ET 当前 上 本 
22. 


(7) OpenJDK 


OpenJDK 项 目地 址 为 http://openjdkjava.net。OpenJDK 是 开源 的 JDK， 从 1.7 版 本 开始 成 为 官方 JDK 的 先行 版 本 ， 因 此 是 Java 开 发 者 研究 Java 发 展 的 第 一 线 的 资源 。 同 时 也 是 活跃 的 Linux 发 行 版 本 
Ubuntu 和 Fedora 等 默认 安装 的 JDK 版 本 。OpenJDK 项 目 情况 见 表 1-16。 


表 1-16 ”OpenJDK 项 目 情况 简 表 


项 目 名 称 当前 版 本 
OpenJDK JDK8.0 


小 白 讲堂 


下 面 讲 一 下 JDK 版 本 号 升级 规则 。 

自 JDK 5.0 发 布 开始 ，Java 一 直 以 两 种 方式 发 布 更 新 。 

1) 有 限 升级 (Limited Update) : 包含 新 功能 和 非 安 全 修正 。 

2) 重要 补丁 升级 (Critical Patch Updates，CPUs) : 只 包含 安全 修正 。 

有 限 升 级 发 行 序号 为 20 的 倍数 ， 即 一 个 偶数 ; 重要 补丁 升级 序号 为 顺延 上 一 个 CPUs 的 版 本 号 +5 的 倍数 并 取 奇 数 (必要 时 +1) 。 


举例 来 说 ， 下 一 个 有 限 升 级 的 版 本 号 为 7u40， 那 么 接 下 来 的 3 个 CPUs 版 本 号 依次 为 40+5=7u45、45+5+1=7u51 和 51+5=7u55。 再 下 一 个 有 限 升 级 的 版 本 号 为 T7460， 随后 的 CPUs 版 本 号 依次 为 T7065、7u71 
和 7u75。 


这 种 命名 规则 会 为 重要 补丁 升级 保留 几 个 版 本 序号 ， 以 便 新 的 CPUs 版 本 号 可 以 取 区 间 值 和 而 不 是 在 最 新 版 本 号 上 顺延 。 


[由 与 年 龄 无 关 ， 个 人 很 厌恶 30 岁 分 界 的 观点 。 


1.5 ” ”Java 领域 的 其 他 REST 实 现 


Java 领 域 的 REST 实 现 以 是 否 遵循 JAX-RS 标 准 分 为 两 个 阵营 。 前 者 为 参考 实现 之 外 的 厂商 实现 ， 后 者 要 么 出 现 较 早 、 要 么 干脆 跳出 了 标准 的 框架 ， 以 自身 所 追求 的 目标 ， 比 如 性 能 、 框 架 一 致 性 等 ， 实 现 
了 一 套 独 有 的 对 REST 开 发 的 支持 。 本 节 将 做 概括 性 介绍 ， 以 便 读者 有 所 对 比 和 选择 。 


1.5.1 其 他 JAX-RS 实 现 


JAX-RSs 标 准 发 布 后 ， 诸 多 厂商 推出 了 自己 的 基于 JAX-RS 标 准 的 实现 。 其 中 比较 有 影响 力 的 应 该 是 来 自 JBoss 社区 的 RESTEasy 和 来 自 Apache 社 区 的 CXF。 本 节 将 简 述 这 两 个 项 目 。 如 果 读 者 的 项 目 确实 
和 它们 结合 得 比较 紧密 ，Jersey 未 必 是 最 佳 选 择 ， 读 者 尽 可 “拥抱 ”这 两 个 基于 JAX-RS 标 准 的 项 目 。 


1.JBoss 的 RESTEasy 


RESTEasy 是 JBoss 社区 提供 的 JAX-RS 项 目 。 值 得 说 明 的 是 ，JBoss 这 一 名 词 目前 已 经 不 再 代表 Java EE 容 器 ， 曾 经 的 JBoss 已 经 更 名 为 WildFly， 而 JBoss 一 词 现在 特 指 RedHat 公 司 旗下 的 开源 社区 。 
RESTEasy 自 2009 年 1 月 第 一 个 GA 版 本 以 来 ， 发 展 到 3.0.x。 从 版 本 3.0.0.Final 开 始 支持 JAX-RS 2.0。 


官方 文档 提供 单 页 面 HTML、 按 章节 HTML 和 PDF 三 种 格式 ， 可 以 按照 阅读 习惯 选择 。 参 见 : 


http://www.jboss.org/resteasy/docs 


该 项 目 源 代 码 由 GitHub 托 管 ， 地 址 为 : 


https://github.com/resteasy/Resteasy 


项 目下 载 由 http://sourceforge.net 托 管 ， 当 前 版 本 为 3.0.7.Final。 地 址 为 : 


http://sourceforge.net/projects/resteasy /files/Resteasy%20JAX-RS 


2.Apache 的 CXF 


CXF 是 Apache 开 源 社区 提供 的 JAX-RS 项 目 ，CXF 的 名 称 是 由 Celtix 项 目 和 XFire 项 目 合并 而 来 。 其 中 Celtix 由 IONA Technologies 开 发 ，XFire 来 自 Codehaus。CXF 是 JAX-WS 的 著名 实现 ， 同 时 实现 了 
JAX-RS， 从 版 本 2.7.0 开 始 几乎 全 面 支持 JAX-RS 2.0 全 部 特性 。 官 方 文档 参见 http://cxf.apache.org/docs/jax-rs.html。 


Apache CXF 当 前 版 本 为 2.7.11， 下 载 地 址 为 : 


http://cxfapache.org/download.html 
源 代码 由 Apache 的 GIT 服 务 器 托管 ， 地 址 为 : 


https:/ /git-wip-us.apache.org/repos/asf?p=cxf.git 


源 代 码 克 隆 命令 参考 如 下 : 


git clone https://git-wip-us.apache.org/repos/asf/cxf.git 


1.5.2 ”其 他 REST 实 现 


JAX-Rs 是 Java 领 域 实现 REST 式 Web 服 务 的 标准 规范 。 但 需要 注意 的 是 ，Java 领 域 支持 REST 式 Web 服 务 开发 的 工具 未 必 遵 循 JAX-Rs 规 范 。 其 中 ， 大 名 易 昂 的 Spring MVC 就 是 一 个 支持 REST 开 发 的 非 
JAX-RS 规 范 的 实现 。 本 节 将 带领 读者 认识 Java 领 域 的 非 JAX-RS 规 范 的 著名 REST 支 持 工 


(1) Restlet 项 目 


Restlet 是 一 款 遵 从 REST 风 格 的 、 基 于 Java 平 台 的 轻 量 级 框架 。Restlet 是 开源 的 ， 提 供 REST 开 发 的 完整 支持 。Restlet 官 网 地 址 为 : 


http:/V/restletorg 
Restlet 源 代码 由 GitHub 托 管 ， 地 址 为 : 


https://github.com/restlet 


Restlet 学 习 指 南 文档 地 址 为 : 


http:/ /restlet.org/learn/ tutorial 


(2) LinkedIn 的 Rest.li 


Rest.li 是 社交 网 站 LinkedIn 开 发 的 REST+JSON 的 开源 REST 式 服务 框架 。Rest.li 的 官方 地 址 是 : 


http:/ /rest.li 


如 


st 站 i 源 代码 由 GitHub 托 管 ， 地 址 为 : 


https://github.com/linkedin/rest.li 


文档 的 wiki 地 址 为 : 


https://github.com/linkedin/rest.li/wiki 


(3) Spring WEB MVC 项 目 


Spring 框架 使 用 Gradle 构 建 和 管理 项 目 ， 使 用 GIT 管 理 源 代 码 ， 地 址 为 : 


https://github.com/spring-projects/spring-framework 
Spring-Web 是 Spring 项 目的 一 个 模块 ， 详 情 可 参考 : 


http://spring.io/projects 


Spring-Web 从 3.0 版 本 开始 提供 了 对 REST 式 应 用 开发 的 支持 ， 但 Spring-Web 目 前 并 没有 推出 一 个 实现 JAX-RS 标 准 的 模块 。Spring-Web MVC 模 块 提供 了 REST 功 能 ， 但 没有 采用 JAX-RS 提 出 的 标准 。 
本 质 上 ，Spring-Web MVC 控 制 流程 是 使 用 Controller 处 理 Model 在 某 种 动词 性 的 业务 逻辑 操作 ， 而 JAX-RS 的 控制 流程 是 使 用 资源 类 Resource 处 理 名 词性 的 资源 表述 。 


小 白 讲 堂 


Gradle 是 一 个 基于 Apache Maven 概 念 的 项 目 自动 化 建构 工具 。 和 Maven 使 用 传统 的 XML 配置 项 目 不 同 的 是 ，Gradle 使 用 Groovy 语 言 (一 种 领域 特定 语言 ， 即 DSL) 来 配置 项 目 构建 信息 。Gradle 官 网 地 址 


是 : http://www.gradle.org。 


1.6 ”本章 小 结 


本 章 的 目的 是 为 读者 厘清 在 Java 领 域 开发 REST 式 的 Web 服 务 的 概念 、 上 下 文 关系 等 知识 点 。 先 后 解读 了 REST 这 个 概念 、REST 式 的 Web 服 务 、JAX-RS 2.0 标 准 中 的 重要 概念 。 接 着 对 JAX-RS 2.0 的 参考 


实现 项 目 Jersey 进 行 了 简单 而 全 面 的 概述 。 最 后 介绍 了 其 他 基于 JAX-RS 2.0 标 准 的 项 目 和 其 他 非 JAX-RS 2.0 标 准 的 、 著 名 的 Java 项 目 。 


希望 通过 阅读 本 章 ， 读 者 可 以 扫 清 Java 领 域 开 发 REST 式 的 Web 服 务 的 概念 上 的 障碍 。 下 一 章 将 通过 实际 操作 来 讲解 JAX-RS 2.0 实 现 ， 带 领 读者 实现 从 理论 到 实践 的 飞跃 。 


第 2 章 ”JAX-RS 2.0 快 速 实现 


学 习 和 使 用 一 种 新 技术 ， 说 起 来 并 没有 多 少 玄机 。 相 信 每 一 位 深 得 其 法 的 读者 ， 都 遵循 着 这 样 一 条 学 习 路 线 ， 那 就 是 ， 首 先 了 解 背景 知识 ， 收 集 相关 概念 、 标 准 和 实现 工具 ， 在 脑海 里 形成 根 枝 结构 ， 
希望 第 1 章 已 经 带 给 读者 这 样 的 帮助 。 接 着 就 是 找到 一 个 好 用 的 、 有 引领 性 的 例子 来 快速 学 习 ， 这 是 不 断 成 长 的 过 程 ， 是 走向 “ 枝 繁 叶 茂 ”的 第 一 步 。 当 然 ， 最 后 会 找寻 一 两 本 该 领域 的 权威 书籍 来 深入 掌 
握 ， 最 终 达到 运用 熟练 的 地 步 。 这 是 本 书后 续 章节 希望 为 读者 呈现 的 。 


本 章 是 入 门 章节 ， 希 望 读 者 可 以 掌握 JAX-RX 2.0 应 用 开发 的 相关 技能 。 本 章 可 以 形象 地 比喻 为 通 往 掌握 Java RESTful 开 发 的 快速 干道 ， 读 者 将 从 若干 不 同 场景 的 例子 中 了 解 实现 和 部 署 REST 应 用 的 过 


程 。 


实践 一 个 REST 应 用 需要 考虑 两 点 : 第 一 点 是 如 何 定义 一 个 资源 ， 包 括 以 什么 方式 发 布 一 个 请 求 ， 它 的 输入 和 输出 是 什么 第 二 点 要 考虑 的 是 如 何 部 署 一 个 Java RESTful Web service 应 用 ， 以 匹配 既 有 
的 REST 服 务 类 型 。 


国 峻 去 指 南 “关于 对 资源 设计 和 定位 的 思考 远 不 止 环 章 所 述 ， 详 细 情况 ， 读者 可 以 阅读 第 3 章 。 作 为 入 门 章节 ， 本 章 去 除 “噪声 ”， 让 读者 只 关注 能 实现 REST 的 最 少 知识 。 正 像 迪 米 特 法 则 那样 ， 知 道 
的 最 少时 最 整洁 。 


举 个 例子 ， 有 一 个 资源 是 关于 更 新 设备 的 AP1， 我 们 需要 考虑 该 API 将 以 PUT 方式 发 布 还 是 其 他 方式 发 布 ” 它 的 输入 是 XML 格式 、JSON 格 式 ， 还 是 流 呢 ” 它 的 输出 是 否 覆盖 更 新 设备 所 遇 到 的 所 有 情 
形 ， 输 出 格式 是 否 合理 ， 信 息 是 否 完整 且 合 理 ” 另 一 个 要 考虑 的 是 这 个 关于 设备 的 REST 应 用 是 否 部 署 到 Servlet 容 器 ， 以 及 该 容器 的 版 本 。 带 着 这 样 的 疑问 走 进 本 章 ， 你 一 定 迫 切 地 想 知道 答案 。 首 先 ， 我 们 
必须 做 一 些 准 备 工作 。 


2.1 第 一 个 Java REST 服 务 


本 节 讲 述 基于 Java SE 环 境 的 Jersey 官 方 文档 中 提供 的 示例 simple-service (参考 地 址 : https://jersey.java.net/documentation/latest/user-guide.html) ， 并 在 此 基础 上 扩展 自 定义 的 REST 资 源 服 
务 。 


2.1.1 “环境 准备 
在 动手 之 前 ， 我 们 需要 准备 开发 REST 服 务 的 环境 ， 包 括 JDK、Maven 和 IDE。 
© 阅读 指南 。2.1 节 示例 所 在 目录 是 jax-rs2-guide\sample\2\0simple-service。 


源 代 码 地 址 为 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/0simple-service。 


1. 配 置 JDK 


Jersey 对 JDK 的 版 本 要 求 是 1.6 及 以 上 ， 读 者 可 根据 项 目 情况 ， 参 考 1.4 节 的 Jersey 2 依赖 和 GlassFish 项 目 中 的 讲述 ， 选 择 JDK 1.6 以 后 的 版 本 来 开发 基于 Jersey 的 REST 项 目 。 本 章 示例 使 用 的 操作 系统 是 
Windows 7 的 64 位 版 本 ，JDK 版 本 是 jdk-7u25-windows-x64.exe。 下 载 并 安装 好 JDK， 然 后 修改 系统 环境 变量 : 添加 JAVA_HOME 参 数 ， 并 将 其 bin 目 录 追 加 到 path 中 。 示 例如 下 。 


JAVA HOME=D:\Program Files\Java\jdk1.7.0_ 25 
Path=%JAVA HOMES\bin; 


设置 完毕 后 ，Windows 操 作 系统 需要 重启 控制 台 使 Java 生 效 ; 在 Linux 下 ， 需 要 使 用 命令 source path2profile 启 用 Java。 


2. 配 置 Maven 


Maven 是 Apache 的 项 目 ， 是 当今 流行 的 项 目 构建 工具 。 读 者 可 以 通过 其 官网 (http://maven.apache.org) 了 解 更 多 信息 。 需 要 注意 的 是 ，Maven 版 本 中 的 3.x 相 比 2.x 有 性 能 上 的 优势 ， 推 荐 使 
Maven 3.x。Maven 3.0.x 和 Maven 3.1.x 的 区 别 在 于 其 内 部 实现 ， 作 为 用 户 使 用 而 言 ， 笔 者 没有 推荐 倾向 。 对 于 工具 版 本 的 选择 ， 并 不 推荐 使 用 最 新 版 ， 除 非 新 版 本 更 加 稳定 可 靠 。 比 如 3.0.5 这 个 版 本 是 
Maven 3.0.x 的 修复 和 维护 版 本 ， 这 意味 着 该 版 本 较 之 前 面 的 版 本 更 趋 稳定 。 作 为 演示 ， 本 例 选择 的 是 最 新 版 本 maven-3.1.0。 下 载 并 解压 Maven， 然 后 在 系统 环境 变量 中 定义 M2_HOME 并 指向 Maven 解 
压 后 的 路 径 ， 在 Path 中 添加 M2_HOME 下 的 bin 目 录 ,或 定义 M2 变量 为 M2_HOME 下 的 bin 目 录 ， 然 后 将 其 添加 到 Path 中 ， 如 下 所 示 。 


M2_HOME=D:\-aquarius\apache-maven-3.1.0 
MAVEN OPTS=-Xms128m -Xmx512m 
Path=%M2_ HOMES\bin; 


MAVEN_OPTS 用 于 定义 Maven 运 行 时 JVM 虚 拟 机 参数 ， 通 常 至 少 需要 定义 VM 堆 的 最 大 值 -Xmx 以 支持 构建 较 大 的 项 目 。Maven 的 版 本 测试 命令 是 mvn-v， 其 测试 结果 如 下 所 示 。 


mm 一 

Apache Maven 3.1.0 

(893ca28algda9d5f51ac03827af98bb730128f9f2; 2013-06-28 10:15:32+0800 
) 


Maven home: D:\-aquarius\apache-maven-3.1.0 

Java version: 1.7.0 25, vendor: Oracle Corporation 

Java home: D:\Program Files\Java\jdk1.7.0 25\jre 

Default locale: zh CN, platform encoding: GBK 

OS name: "windows 7", version: "6.1", arch: "amd64", family: "windows" 


3. 使 用 IDE 


也 许 读者 希望 就 某 种 IDE 讲 述 示例 ， 由 于 本 书 的 全 部 示例 都 是 基于 Maven 的 Java 项 目 ， 当 今 的 主流 IDE 对 集成 Maven 的 支持 都 非常 好 ， 因 此 本 书 在 讲述 技术 细节 时 ， 将 不 特别 针对 某 种 IDE 的 使 用 有 倾向 
性 的 推荐 和 描述 。 


本 书 尽 可 能 确保 所 提供 的 全 部 示例 的 源 代码 在 以 下 IDE 中 编译 、 运 行 和 测试 无 误 。Eclipse Indigo (3.7.2) IDE 中 的 服务 器 还 是 要 自行 配置 ， 否 则 纯 属 环境 配置 问题 ， 而 非 示例 代码 问题 。 下 面 是 常见 的 
1DE 列 表 。 


“Eclipse Juno (4.3) 。 


"IntellJ IDEA 12.1.6+。 


* NetBeans IDE 7.3.1。 


读者 可 以 根据 个 人 使 用 偏好 选择 IDE。Jersey 的 开发 和 Web 开 发 相 比 ， 形 式 上 基本 一 致 ， 所 以 不 必 更 换 1DE 来 运行 本 书 示例 。 


2.1.2 ”创建 服务 
准备 好 环境 ， 我 们 就 可 以 动手 操作 了 。 我 们 从 Maven 原 型 开始 创建 ， 然 后 测试 并 分 析 该 示例 。 


1. 从 Maven 原 型 创建 项 目 


Jersey 官 方 文档 中 提供 的 例子 simple-service 是 一 个 Maven 原 型 项 目 ， 我 们 从 这 里 开始 。 所 谓 “ 原 型 项 目 ” 即 指 通 过 Maven 命 令 即 可 从 Maven 中 央 仓 库 取 回 一 个 已 经 具备 基本 功能 、 依 赖 包 完好 、 编 译 
和 运行 测试 无 误 的 示例 项 目 。mvn archetype: generate 字 面 解读 为 : 以 指定 的 原型 为 模板 ， 生 成 或 者 创建 新 的 Maven 项 目 。 在 控制 台 执行 如 下 命令 来 生成 我 们 想 要 的 simple-service 项 目 ， 项 目的 目标 存 
储 路 径 由 读者 自行 选择 。 


mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 ~DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false -DgroupId=com.example -Dartif 


控制 台 命令 成 功 执行 后 ， 会 在 当前 目录 下 创建 imple-service 目 录 。 该 目录 包含 了 最 简 REST 示 例 ， 即 simple-service 项 目的 全 部 源 代码 。 


国 冶 沪指 南 如 果 读 者 在 确保 林地 配置 无 误 的 情况 下 ,执行 上 述 命令 失败 ， 说 明 该 官方 例子 项 目 已 经 失效 或 者 由 于 非 技术 原因 导致 的 无 法 访问 ， 读 者 可 以 直接 使 用 本 书 提供 的 源 代码 。Maven 管 理 的 项 
目 版 本 清晰 ， 一 般 活 跃 的 项 目的 失效 的 可 能 性 比较 低 。 


2. 测 试 项 目 可 用 性 


simple-service 项 目 在 本 地 创建 成 功 后 ， 首 先 要 确定 该 项 目 在 本 机 的 可 用 性 。 进 入 simple-service 项 目的 根 目录 ， 然 后 执行 Maven 的 测试 命令 ， 若 simple-service 项 目 在 环境 中 已 经 可 用 ， 则 控制 台 将 输 
出 如 下 信息 。 


simple-service>mvn clean test 

[INFO] -~------ 一 -一 -一 -一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 
[INFO] Building simple-service 1.0-SNAPSHOT 

[INFO] ~~- 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 


Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 

[IMEO] =———-—— 
[INFO] BUILD SUCCESS 

LEMEG) eo 
[INFO] Total time: 4.791s 

[INFO] Finished at: Sat Jul 27 12:10:43 CST 2013 

[INFO] Final Memory: 13M/224M 


该 项 目 默认 使 用 JDK 1.6 编 译 ， 如 果 用 户 的 JDK 版 本 不 同 ， 在 执行 测试 之 前 ， 首 先 要 修改 Maven 的 配置 文件 pom.xml， 设 置 编译 插件 的 JDK 版 本 参数 。pom.xml 文 件 位 于 项 目 根 目 录 下 。 使 用 读者 熟悉 的 
编辑 器 打开 pom 文 件 ， 下 面 以 文本 编辑 器 为 例 : 


notepad D:\simple-service\pom.xml 


搜索 关键 字 maven-compiler-plugin， 定 位 <source> 和 <target> 两 行 。 以 JDK 1.7 为 例 ， 修 改 为 <source>1.7</source> 和 <target>1.7</target>， 保存 并 退出 。 最 后 执行 Maven 命 令 “mvn clean 
test” 进 行 测试 。 


3. 项 目 分 析 


项 目测 试 通 过 意味 着 本 地 环境 没有 问题 了 ， 接 下 来 可 以 开始 学 习 simple-service 项 目 了 ， 为 下 一 步 扩 展 项 目 做 好 准备 。 


在 simple-service 项 目的 根 目 录 执 行 “tree/f” 命令 ， 可 以 纵览 simple-service 的 文件 结构 ， 如 图 2-1 所 示 。 


在 图 2-1 所 示 的 目录 结构 中 ， 对 开发 者 有 价值 的 内 容 包 括 源 代码 Main.java、MyResource.java 和 测试 代码 MyResourceTest.java。 


加 


首先 ， 定 位 该 项 目 中 的 有 用 信息 以 去 除 项 目 中 的 噪声 。 什 么 是 噪声 呢 ? 无论 使 用 哪 一 种 IDE 做 开发 ， 其 自身 都 会 产生 具有 该 IDE 方 言 的 项 目 文件 。 除 非特 殊 情 况 ， 我 们 不 必 理 会 这 些 项 目 文件 ， 如 果 是 
队 开发 ， 在 提交 到 版 本 控制 库 的 时 候 ， 应 该 对 其 过 滤 (使 用 GIT 做 SCM 时 ， 过 滤 文 件 位 于 项 目 根 目录 ， 名 称 为 .gitignore) 。target 目 录 是 Maven 的 生成 目录 ， 类 似 构建 工具 Ant、Gradle 的 build 或 者 bin 
录 ， 我 们 也 可 以 忽略 。 


小 白 讲堂 


Eclipse 产 生 的 项 目 文件 包括 .settings 目 录 ， 以 及 .classpath 和 .project 文 件 。 
Intell] 产 生 的 项 目 文件 包括 .idea 目 录 ， 以 及 项 目 同名 的 .iml 文 件 。 
NetBeans 产 生 的 项 目 文件 包括 nb-configuration.xml 文 件 。 


(1) 资源 类 分 析 


套用 Web 开 发 中 典型 的 三 层 逻 辑 ， 资 源 类 位 于 逻辑 分 层 的 最 高 层 一 一 APl 层 ， 其 下 为 Service 层 和 数据 访问 
于 对 外 公布 REST 服 务 接口 。 其 下 的 两 层 ，REST 应 用 的 开发 和 标准 Web 开 发 的 区 别 不 是 很 大 。 


， 如 图 2-2 所 示 。 在 三 层 逻 辑 中 ，API 层 用 于 对 外 公布 接口 ， 对 于 REST 应 用 ，API 层 的 资源 类 


本 例 中 的 API 层 资源 类 是 MyResource， 代 码 示例 如 下 。 


Package com.example; 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


ed 

关注 点 1: 

资源 路 径 

@Path 
("myresource" 


public class MyResource { 
ea 


关注 点 2 
: 资源 方法 
@GET 
@Produces 
(MediaType.TEXT PLAIN 
) 


public String getIt() { 
return "Got it!"; 
} 
} 


在 这 段 代 码 中 ， 资 源 类 MyResource 使 用 了 JAX-Rs 标 准 中 定义 的 @Path 注 解 来 声明 名 为 myresource 的 资源 路 径 ， 见 关注 点 1。 该 类 只 有 一 个 处 理 HTTP 协 议 的 GET 方 法 的 getlt( 方 法 ， 没 有 输入 参数 ， 
输出 是 一 个 String 类 型 ， 传 输 格式 是 字符 串 类 型 (MediaType.TEXT_PLAIN) ， 返 回 字符 串 值 是 “Got it! ”， 见 关注 点 2。 


在 没有 测试 、 运 行 这 个 例子 之 前 ， 我 们 可 以 推测 通过 REST 访 问 getlt( 方 法 的 资源 路 径 如 下 ， 接 下 来 的 讲述 将 验证 该 资源 路 径 。 资 源 路 径 即 是 对 外 公布 的 REST 服 务 接口 。 


HITE 
服务 器 路 径 /REST 
服务 名 称 /myresource/ 


填 - Administrator: CN WIndows\system32\cmd.exe 和 生硬 


D:‘\simle-servicetree /ff 
Folder PATH listine for volume d 
Dlum serial mumber 1s 出 36 一 3EL 


pom. Km 


ep 
上 一 一 一 main 
-一 一 一 javra 
一 | 册 
上 一 一 一 Exarmbp]e 
Nain. 1avwa 
NyrResource,. 1ava 


| 上 一 一 一 t{ 已 号 十 
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| 上 一 一 一 com 
LL 


-一 一 一 Examp]e 
JrRESOUECEETESt。]avaa 


一 人 人 人 Target 


上 一 一 &1asses 
| | 


| i 

| -一 一 一 examp1e 

Nain. class 

| Nyhasource. class 


| 一 generated-sources 
| 上 一 一 一 amnnotations 
上 一 zenerated-test-sources 
| 上 一 一 一 teEst 一 anmotations 
F———surefire-reports 


| com. Example, Mvhesourcelest,. txt 
| TEST-com. example. lvhesorcelest,. xml 


[test-classes 
上 -一 一 一 com 


B= 忆 XarD] 


NvrResourcelest. class 


图 2-1 ”simple-service 项 目 源 代码 组 织 结构 


Service 兵 


所 访问 乓 


(2) 入 口 类 分 析 


因为 这 是 一 个 Java SE 的 应 用 ， 所 以 需要 一 个 入 


口 类 来 启动 服务 器 并 加 载 项 


图 2-2” 训 辑 分 层 


目 资源 。 对 于 Java EE 的 应 用 则 无 须 定义 这 样 的 入 


类 ， 


为 Java EE 容 器 本 身 扮演 着 入 


口 类 的 角色 。Main 类 是 simple-service 


项 目的 主 类 ， 即 入 口 类 ， 代 码 示例 如 下 。 


Package com.example; 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
public class Main { 


// 

关注 点 1 

: 服务 器 路 径 
public static final String BASE URI = "http://localhost:8080/myapp/"; 
public static HttpServer startServer() { 


final ResourceConfig rc = new ResourceConfig() .packages 
("com.example" 


// 
关注 点 3 
: Grizzly HTTP 


服务 器 
return GrizzlyHttpServerFactory.createHttpServer 
(URI .create 
(BASE URI 
yr 
} 
public static void main 
(String[] args 
) throws IOException { 
final HttpServer server = startServer(); 
System.out .println 
(String.format 
("Jersey app started with WADL available at " 
+ "Ssapplication.wadl\nHit enter to stop ithttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/...", BASE URI 
Py 
System.in.read(); 
server.shutdownNow (); 


Main 类 定义 了 HTTP 服 务 器 的 路 径 (BASE_URI) ， 即 http://localhost:8080/myapp/， 见 关注 点 1。 在 其 构造 中 映射 了 源 代码 中 资源 所 在 的 包 名 new 
ResourceConfig0.packages (“com.example”) ， 这 意味 着 ,服务 器 启动 时 会 自动 扫描 该 包 下 的 所 有 类 ， 根 据 该 包 中 所 含 类 的 REST 资 源 路 径 的 注解 ， 在 内 存 中 做 好 映射 ， 见 关注 点 2。 这 样 一 来 ， 客 
端 请 求 指定 路 径 后 ， 服 务 器 就 可 以 根据 映射 分派 请 求 给 相应 的 资源 类 实例 的 相应 方法 了 。 这 就 是 Jersey 中 的 IoC 机制。 这 个 例子 不 是 运行 在 Servlet 容 器 中 的 ， 相 反 ， 它 是 一 个 Java SE 应 用 。 该 服务 自 带 了 
HTTP 服 务 器 的 实现 ， 本 例 使 用 的 服务 器 是 Grizzly， 见 关注 点 3。 


宅 人 坑 事 


在 1.4 节 中 ， 我 们 对 Gtizzly 有 过 介绍 ， 这 里 额外 要 说 的 是 ，Gtizzly 是 Jersey 提 供 的 集成 测试 中 默认 的 内 广 测 试 服务 器 ， 有 了 Grizzly， 我 们 就 可 以 在 不 启动 额外 Servlet 容 器 服务 器 的 情况 下 ， 测 斌 REST 服 务 。 
这 点 对 于 Maven 老 用 户 来 说 ， 一 定 会 联想 到 在 运行 Servlet 容 器 测试 时 使 用 Jetty 插 件 的 情形 。 略 有 不 同 的 是 ，Jetty 的 角色 之 于 Maven 是 一 个 声明 式 的 〈 配 置 参数 ) 、 无 须 编码 的 插件 ， 而 Grizzly 是 编码 式 的 。 


(3) 测试 类 分 析 


最 后 我 们 来 看 看 真正 用 于 单元 测试 的 测试 类 MyResourceTest。 它 只 有 一 个 测试 方法 testGetlt() 用 来 测试 MyResource 类 公布 的 资源 路 径 myresource。 其 代码 示例 如 下 。 


Package com.example; 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
public class MyResourceTest { 
// 


private HttpServer server; 
Private WebTarget target; 
// 


关注 点 2 
: 准备 测试 环境 
@Before 
public void setUp () throws Exception { 
server = Main.startServer () 7 
Client c = ClientBuilder.newClient () 7 
target = c.target 
(Main.BASE URI 


主 
测试 环境 
QAfter 
public void tearDown() throws Exception { 
server .shutdownNow (); 


} 
// 
关注 点 4 
: 测试 GET 
方法 
Q@Test 
public void testGetIt() { 
String responseMsg = target.path 
("myresource" 
) .request () .get 
(String.class 
J 
assertEquals 
("Got it!", responseMsg 
); 
} 
} 


MyResourceTest 定 义 了 两 个 全 局 字段 ， 分 别 是 Grizzly 服 务 器 类 HttpServer 和 JAX-RS 2.0 的 客户 端 资源 定位 类 WebTarget， 见 关注 点 1。 


注解 为 @Before 的 setUp() 方 法 是 JUnit 测 试 前 要 执行 的 方法 ， 为 测试 准备 环境 。 首 先 启动 Grizzly 服 务 器 ， 然 后 实例 化 一 个 Client， 最 后 将 服务 器 的 资源 地 址 作为 参数 ， 传 给 客户 端 示例 ， 获 取 到 客户 端 
资源 定位 类 实例 target， 见 关注 点 2。 


testGetlt() 方 法 用 于 测试 GET 方 法 ， 使 用 资源 定位 类 WebTarget 实 例 target 向 myresource 资 源 发 出 get 请 求 ， 将 返回 值 作为 相等 断言 的 输入 参数 ， 和 “Got it! ”进行 比 对 ， 见 关注 点 4。 


注解 为 @After 的 方法 tearDown() 在 测试 结束 后 执行 ， 以 释放 测试 环境 中 的 资源 ， 如 停止 服务 器 实例 、 释 放 资 源 等 ， 见 关注 点 3。 这 里 需要 注意 的 是 ， 释 放 资 源 过 程 无 须 处 理 客户 端 实例 ， 该 实例 的 连接 
已 经 在 获取 响应 实体 时 断 开 ， 详 见 后 文 的 讲述 。 


到 此 ， 我 们 已 经 掌握 了 simple-service 项 目 。 在 入 门 学 习 中 ， 模 仿 是 以 后 做 到 收 放 自如 的 第 一 步 。 接 下 来 ， 我 们 重用 Main 作 为 环境 支撑 ， 模 仿 MyResource 写 一 个 自 定义 的 资源 类 ， 并 进行 扩展 性 的 尝 
试 : 引入 实体 类 、 逻 辑 分 层 类 ， 支 持 更 多 的 传输 类 型 。 还 记得 本 章 开 始 时 关于 设计 一 个 更 新 设备 的 API 的 疑问 吗 ?继续 轻松 的 学 习 之 旅 吧 。 


2.1.3 扩展 服务 


在 Maven 原 型 示例 的 基础 上 进行 模仿 来 扩展 该 项 目的 REST 服 务 接口 是 本 节 的 第 二 个 任务 ， 通 过 这 一 过 程 实现 对 Jersey 使 用 的 初步 认识 。 下 面 我 们 要 完成 的 任务 是 实现 一 个 更 新 设备 的 AP1， 这 将 包括 开 
发 设备 实体 类 、 资 源 类 和 逻辑 分 层 类 ， 然 后 对 其 进行 测试 ， 以 检验 我 们 的 成 果 。 


1. 增 加 设备 实体 类 


资源 类 和 逻辑 分 层 类 在 图 2-2 中 已 经 展示 ， 实 体 类 是 资源 自身 的 信息 ， 用 于 序列 化 和 持久 化 资源 。 设 备 的 实体 类 用 于 传输 和 持久 化 设备 资源 ， 设 备 的 实体 类 命名 为 Device， 该 类 是 一 个 最 基本 的 POJO 
类 ， 包 含 两 个 属性 ， 分 别 是 设备 的 IP 和 设备 的 状态 。 其 代码 示例 如 下 。 


@XxmlRootElement 
(name = "device" 
) 
public class Device { 
private String deviceIp; 
private int deviceStatus; 
public Device() { 
} 
public Device 
(String deviceIp 
) 1 
super (); 
this.deviceIp = deviceIp; 
} 


// 
关注 点 2 


: JAXB 
属性 @XmlAttribute 
public String getIp() { 
return deviceIp; 


} 

public void setIp 
(String deviceIp 
1 


this .deviceIP = deviceIp; 


} 
Q@XmlAttribute 
public int getStatus() { 
return deviceStatus; 
} 
public void setStatus 
(int deviceStatus 


{ 


} 
} 


this.deviceStatus = deviceStatus; 


该 类 标注 了 JAXB 标 准 定义 的 @XmlRootElement 和 @XmlAttribute 注 解 ， 以 便 将 Device 类 和 XML 格式 的 设备 数据 相互 转换 并 在 服务 器 和 客户 端 之 间 传 输 ， 见 关注 点 1 和 关注 点 2。 
小 白 讲堂 


Jersey 内 部 使 用 AXB 处 理 Java 类 (POJO) 和 XML 格 式 的 信息 、JSON 格 式 的 信息 映射 ,JAXB 通 过 POJO 中 定义 的 XML 注 解 ( 比 如 @XmlRootElement 代 表 根 节点 ，(@XmlAttribute 代 表 一 个 节点 的 属性 等 ) 将 
其 与 XML 格式 的 信息 对 应 起 来 。 


2. 增 加 设备 资源 类 


创建 了 设备 实体 类 后 ， 我 们 需要 一 个 资源 类 来 公布 设备 的 REST API。 源 代码 中 已 经 提供 了 资源 类 MyResource， 为 实现 设备 管理 ， 我 们 模仿 该 类 ， 创 建设 备 资 源 类 DeviceResource， 代 码 示例 如 下 。 


@Path 
("device" 


public class DeviceResource { 


private final DeviceDao deviceDao; 
public DeviceResource () { 
deviceDao = new DeviceDao () 7 


@Produces 
({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML } 
) Ls 中 


public Device get 
(@QueryParam 
("ip" 
) final String deviceIp 
) { 

Device result = null; 

if 

(deviceIp != null 
) { 


result = deviceDao.getDevice 
(deviceIp 
} 


return result; 


@PUT 

@Produces 
({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML } 
) 人 是 


Public Device Put 
(final Device device 
{ 
Device result = null; 
if 
(device != null 
{ 
result = deviceDao.updateDevice 
(gevice 
} 


return result; 


在 这 段 代 码 中 ， 关 注 点 2 中 的 GET 方 法 和 2.1.2 节 定义 的 GET 方 法 作用 相同 ， 用 于 获取 设备 信息 ， 输 入 参数 devicelp 是 以 设备 IP 作 为 查询 条 件 ， 输 出 是 设备 实体 类 的 实例 ， 其 表述 格式 可 以 是 JSON 或 者 


XML。 关 注 点 3 是 DeviceResource 类 处 理 HTTP 协 议 的 PUT 方法 。put() 方 法 定义 了 两 个 注解 ，@PUT 是 标识 处 理 PUT 请 求 ，@Produces 是 标识 返回 实体 的 类 型 ， 本 例 中 同时 支持 JSON 格 式 和 XML 格式 。 细 
心 的 读者 会 质疑 持久 层 Dao 类 DeviceDao 的 实例 化 是 在 资源 类 中 完成 的 ， 见 关注 点 1， 可 能 会 发 现 这 不 符合 三 层 设 计 ， 也 不 符合 loC。 我 们 会 在 后 续 示 例 中 逐渐 做 到 更 加 严谨 ， 这 只 是 第 一 个 入 门 例 子 ， 放 轻 
松 。 


3. 增 加 设备 逻辑 类 


本 例 演示 了 简单 的 分 层 结构 ， 数 据 的 持久 化 由 DeviceDao 类 完成 ， 该 类 简单 地 模拟 了 设备 持久 化 。 其 示例 代码 如 下 。 


public class DeviceDao { 
ConcurrentHashMap<String, Device> fakeDB = new ConcurrentHashMap<>(); 
public DeviceDao() { 
// 
关注 点 1 
: 测试 数据 ， 初 始 化 了 两 个 设备 实例 
fakeDB.put ("10.11.58.163", new Device("10.11.58.163") ) 
fakeDB.put ("10.11.58.184", new Device("10.11.58.184")); 
} 
public Device getDevice (String ip) { 
return fakeDB.get (ip); 
} 
Public Device updateDevice (Device device) { 
String ip = device.getIp(); 
fakeDB.put (ip, device); 
return fakeDB.get (ip); 


在 这 段 代码 中 ，DeviceDao 类 简单 地 使 用 HashMap 实 现 了 内 存 级 别 的 持久 化 。 为 了 单元 测试 的 需要 ， 本 例 使 用 了 硬 编码 的 测试 数据 ， 持 久 层 加 载 时 ， 为 测试 环境 初始 化 了 两 个 设备 实例 ， 见 关注 点 1。 
这 部 分 代码 在 实际 项 目的 单元 测试 中 ， 不 要 使 用 硬 编 码 ， 可 以 使 用 内 存 数据 库 比如 H2、Derby 等 替换 ， 在 集成 环境 中 ， 应 使 用 真实 的 数据 库 进行 替换 。 


2.1.4 ”测试 和 运行 服务 


到 此 ， 完 成 了 simple-service 扩 展 的 代码 开发 部 分 ， 接 下 来 为 代码 编写 单元 测试 类 ， 以 检验 扩展 的 REST 接 口 是 否 正常 工作 。 


DeviceResourceTest 类 模仿 测试 类 MyResourceTest， 分 别 测试 了 上 述 的 GET 和 PUT 请 求 处 理 方法 ， 示 例 代 码 如 下 。 


Public class DeviceResourceTest { 
private HttpServer server; 
private WebTarget target; 
@Before 
public void setUp() throws Exception { 
server = Main.startServer (); 
final Client c = ClientBuilder.newClient (); 
target = c.target (Main.BASE URI); 
} 
@After 
Public void tearDown () throws Exception { 
SerVer .ShutqownNow () 
关注 点 1 
: 测试 GET 
方法 
@Test 
public void testGetDevice() { 
final String testIp = "10.11.58.184"; 


final Device device = target.path ("device") 
.queryParam("ip", testIp) .request() .get (Device.class); 
// 


Assert .assertEquals (testIP ,device.getIp()); 


EE 
关注 点 4 
: 测试 PUT 
方 ; 
@Test 
public void testUpdateDevice() { 
final String testIp = "10.11.58.163"; 
final Device device = new Device (testIp); 
device.setStatus (1) 7 
Entity<Device> entity = Entity.entity (device, MediaType.APPLICATION XML TYPE) ; 
final Device result = target.path ("device") .request () .Put (entity, Device.class); 


// 


5 
状态 的 断言 
Assert.assertEquals (1, result.getSstatus()); 


} 


GET 测 试 方法 testGetDevice() 测 试 资源 路 径 为 device 的 get 请 求 ， 见 关注 点 1。 在 关注 点 2，target 传 递 了 一 个 字符 串 参数 ip， 其 值 为 “10.11.58.184”。 断 言 验证 返回 的 设备 IP 是 否 与 预期 相同 ， 见 关注 
点 3。PUT 测 试 方法 testUpdateDevice(0) 创 建 了 一 个 Device 实 例 ， 并 以 put 方 法 将 其 提交 到 device 资 源 路 径 ， 见 关注 点 4。 断 言 验证 返回 设备 状态 是 否 与 预期 一 致 ， 见 关注 点 5。 


完成 测试 类 后 ， 打 开 控 制 台 ， 在 项 目的 存储 目录 再 次 运行 “mvn clean test” 命 令 ， 如 果 测 试 通过 ， 即 断言 验证 成 功 ， 说 明 扩展 实现 已 经 成 功 结束 。 


宅 人 坑 事 


关于 单元 测试 ， 想 和 诸 君 分 享 一 点 体会 。 单 元 测试 是 对 实现 方法 所 设置 的 第 一 道 检验 屏障 ， 是 持续 集成 中 至 关 重 要 的 环节 ， 是 质量 保证 体系 中 测试 覆盖 率 的 基础 。 成 为 优秀 开发 者 就 要 遵守 良好 的 习 
惯 ， 单 元 测试 不 可 和 忽视， 甚至 应 该 遵循 测试 先行 、 测 试 驱动 开发 这 些 软件 工程 中 优秀 的 方法 论 。 


如 果 开 发 者 写 不 好 单元 测试 或 者 忽略 其 重要 性 ， 将 这 一 步骤 交 由 工具 来 生成 ， 以 便 完 成 集成 测试 的 流程 和 代码 徐 盖 率 的 KPI， 那 么 ， 笔 者 所 持 的 观点 是 ， 这 是 一 种 倒退 性 实践 ， 极 力 反对 这 种 方式 。 


最 后 ， 我 们 运行 Main 类 ， 通 过 浏览 器 来 体验 一 下 第 一 个 REST 服 务 。 在 浏览 器 地 址 栏 中 输入 http://localhost:8080/myapp/device?ip=10.11.58.184， 预 期 得 到 的 输出 为 : 
<device"10.11.58.184"status="0"/>。 同 时 ， 这 个 测试 也 验证 了 前 文中 推测 的 资源 地 址 URL 规 则 : 


HTTP 
服务 器 路 径 /REST 
服务 名 称 /myresource/ 


到 此 ， 我 们 已 经 快速 掌握 了 一 个 非常 简单 的 Jersey 2 的 Java SE 应 用 。 接 下 来 ,我们 介绍 更 加 常用 的 基于 Servlet 容 器 的 REST Web 服 务 。 


2.2 第 一 个 Servlet 容 器 服务 


上 一 节 讲 述 的 REST 服 务 是 基于 Java SE 环境 的 ， 本 节 将 介绍 Java EE 环境 下 的 REST 服 务 ， 即 REST 式 的 Web 服 务 。 接 下 来 介绍 基于 Servlet 环 境 的 Jersey 官 方 示例 simple-service-webapp， 并 演示 这 个 
Web 服 务 如 何在 Maven 插 件 、Servlet 容 器 和 Java EE 容器 中 运行 该 示例 。 


© 阅读 指南 。2.2 节 示例 所 在 目录 是 jax-rs2-guide\sample\2\0simple-service-webapp-jetty。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/0simple-service-webapp-jetty。 


2.2.1 ”创建 和 分 析 Web 服 务 


simple-service-webapp 项 目 也 是 Jersey 提 供 的 官方 文档 中 的 例子 ， 同 样 是 一 个 Maven 原 型 。 在 控制 台 执 行 如 下 命令 来 生成 Maven 原 型 项 目 simple-service-webapp， 项 目的 目标 存储 路 径 由 读者 自行 
选择 。 执 行 生成 的 命令 如 下 所 示 : 


mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-webapp -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false -DgroupId=com.example -Dartifac 


获取 源 代码 后 ， 通 过 “tree/f” 命 令 纵 览 simple-service-webapp 项 目 ， 如 图 2-3 所 示 。 对 比 simple-service 项 目 可 以 发 现 ， 这 个 Servlet 容 器 内 的 版 本 没有 用 于 服务 器 处 理 的 入 口 类 ， 多 出 来 Web 工 程 中 
两 个 典型 的 文件 index.jsp 和 web.xml。 下 面 通 过 分 析 文 件 来 了 解 Web RESTful 服 务 。 


EAdmMministrator: C\WIindows\system32\cmd.exe 


] pom, xml 
| 


-一 一 一 Sr 


-一 一 一 main 


上 一 一 一 java 


-一 一 一 com 


-一 一 一 cxamp1e 


NyResource. java 


上 一 一 一 reSsourceS 
上 一 一 一 webapp 


lndex, ]sp 


-一 一 一 卫 B-IIF 


1.Servlet 依 赖 


如 图 2-3 所 示 ， 位 于 项 目的 根 目 录 下 的 pom.xml 文 件 是 Maven 项 目 
Servlet 3 版 本 ， 那 么 应 当 首 先 修改 这 个 配置 ， 再 进行 编译 、 测 试 和 调试 。 关 了 


web, xml 


图 2-3 ”simple-service-webapp 项 目 源 代码 组 织 结 构 


的 配置 文件 。 在 pom.xml 文 件 中 ， 示 例 默 认 使 用 的 是 支持 向 下 兼容 Servlet 2.x 的 包 jersey-container-servlet-core。 如 果 读 者 需要 使 用 


FServlet 容 器 的 依赖 包 说 明 ， 见 1.4 节 的 详 述 。pom.xml 中 的 相关 配置 如 下 所 示 。 


lgeryvlet 2,% -=> 

<dependency> 
<groupId>org.glassfish.j y .cont. </groupId> 
<artifactId>jersey-c: Servl e</artifactId> 

</dependency> 

<!--SerVlet 3.x --> 

<dependency> 
<groupId>org.glassfish.jersey.containers</groupId> 
<artifactId>jersey-container-servlet</artifactId> 

</dependency> 


2. 资 源 类 分 析 


使 用 读者 熟悉 的 编辑 器 打开 这 个 资源 文件 ， 这 里 以 文本 编辑 器 为 例 ， 示 例如 下 。 


notepad src\main\java\com\example\MyResource.java 


从 该 类 的 实现 中 可 以 发 现 ，REST 的 资源 类 的 定义 在 Java SE 环境 和 Servlet 容 器 内 是 一 样 的。 由 此 可 以 理解 ，REST 服 务 的 资源 路 径 是 由 服务 器 路 径 和 资源 的 相对 路 径 组 成 。 一 个 项 目的 相对 路 径 是 固定 


的 ， 因 此 资源 类 及 其 子 资源 类 的 定义 并 不 关心 所 处 的 容器 环境 ， 即 服务 器 路 径 ， 而 只 关心 其 相对 的 资源 路 径 。 
3.Web 服 务 首页 分 析 


indexjsp 是 该 示例 的 首页 ， 需 要 指出 的 是 该 示例 其 实 是 一 个 纯 HTML 实 现 ， 虽 然 扩展 名 是 jsp， 但 其 实现 中 并 无 JSP 脚 本 。 使 用 文本 编辑 器 打开 index.jsp 文 件 : notepad src\main\webapp\indexjsp， 
示例 如 下 。 


<html> 

<body> 

<h2>Jersey RESTful Web Application!</h2> 
A 


关注 点 1 

: 资源 路 径 链接 

<p><a href="webapi/myresource">Jersey resource</a> 

<p>Visit <a href="http://jersey.java.net">Project Jersey Website</a> 
for more information on Jersey! 

</body> 

</html> 


在 这 个 简单 的 首页 文件 中 ， 关 键 的 一 行 是 指向 webapi/myresource 这 个 资源 路 径 的 链接 ， 见 关注 点 1。 当 用 户 单 击 这 个 链接 时 ， 浏 览 器 发 起 GET 请 求 ， 资 源 路 径 为 webapi/myresource， 流 程 进入 资源 
类 MyResource 的 getlt() 方 法 。 


4.Web 服 务 配 置 


配置 文件 web.xml 中 定义 了 Web 服 务 的 信息 。 使 用 文本 编辑 器 打开 web.xml 文 件 : 


notepad src\main\webapp\WEB-INF\web.xml 


该 文件 可 以 分 成 3 块 进行 阅读 ， 示 例如 下 。 


第 一 块 : 定义 Servlet 版 本 。 


<?xml version="1.0" encoding="UTF-8"?> 

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/Java EE" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/Java FE http://java.sun.com/ 
xml/ns/Java EE/web-app 2 5.xsd"> 


在 这 段 代码 中 ， 列 出 了 对 Servlet 版 本 的 定义 ， 本 示例 默认 使 用 的 版 本 是 2.5。 需 要 说 明 的 是 ， 如 果 使 用 Servlet 3.0， 那 么 web.xml 文 件 并 不 是 必要 的 ， 我 们 将 在 本 章 稍 后 详 述 。 


第 二 块 : 定义 Servlet。 


<servlet> 
<servlet-name>Jersey Web Application</servlet-name> 
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
<init-param> 
<param-name>jersey.config.server.provider.packages</param-name> 
<param-value>com.example</param-value> 
</init-param> 
<load-on-startup>1</1l0ad-on-startup> 
</servlet> 


在 这 段 代 码 中 ， 对 Servlet 进 行 了 定义 ， 包 括 servlet-name、servlet-class 和 init-param。 对 于 2.5 版 本 ，servlet-class 是 不 可 或 缺 的 。 初 始 化 参数 指定 了 加 载 服务 时 要 扫描 的 包 名 ， 这 里 定义 的 是 
com.example 包 。 


第 三 块 : 定义 servlet-mapping， 即 Servlet 的 作用 域 。 


<servlet-mapping> 
<servlet-name>Jersey Web Application</servlet-name> 
<url-pattern>/webapi/*</url-pattern> 
</servlet-mapping> 


在 这 段 代 码 中 ， 列 出 了 servlet-mapping 的 定义 ， 将 上 述 定义 的 Servlet 的 作用 域 匹 配 到 /webapi/* 的 路 径 上 。 


在 分 析 了 simple-service-webapp 项 目的 内 容 后 ， 我 们 来 测试 这 个 Servlet 项 目 在 容器 内 的 运行 情况 。 在 接 下 来 的 3 个 小 节 中 ， 我 们 将 simple-service-webapp 项 目 分 别 运行 在 三 种 不 同 的 容器 环境 中 ， 为 
不 同 需求 的 读者 提供 参考 ， 分 别 是 Maven 插 件 Jetty、Servlet 容 器 Tomcat 和 Jave EE 容 器 GlassFish。 


2.2.2 Jetty 插 件 与 REST 服 务 


首先 ， 我 们 使 用 Maven+Jetty 这 种 经 典 组 合 来 运行 REST 服 务 ， 即 通过 执行 Maven 命 令 启动 用 于 测试 REST 服 务 的 Servlet 容 器 Jetty 插 件 。 图 2-4 展 示 了 Maven 的 生命 周期 ， 结 合 启动 和 停止 Jetty 的 配置 文 
件 ， 读 者 可 以 清楚 地 了 解 Jetty 插 件 在 Maven 工 程 的 生命 周期 中 所 处 的 位 置 。 


在 Maven 生 命 周期 的 每 个 阶段 中 ， 如 果 失 败 ， 则 流程 结束 于 该 阶段 ， 否 则 执行 至 Maven 命 令 中 定义 的 阶段 ， 并 成 功 结束 。 例 如 ， 执 行 了 如 下 命令 。 


mvn clean install 


如 果 成 功 执行 至 install 阶 段 ， 流 程 将 在 install 结 束 后 ， 成 功 结束 ， 不 再 执行 后 面 的 deploy。 如 果 在 中 间 某 个 阶段 失败 ， 比 如 在 test 阶 段 失败 ， 那 么 流程 结束 于 test， 后 面 的 package 等 阶段 将 不 会 再 执 


generate-SOUT -eS process-sources 


test-compile 


test 


pre-integration-test integration-test post-integration-test 


deploy 


小 白 讲 堂 


图 2-4 Maven 生 命 周 期 示意 


如 果 读者 对 Maven 的 生命 周期 的 各 个 阶段 的 含义 并 不 了 解 ， 那 么 建议 阅读 许 晓 斌 所 著 的 《Maven 实 战 》 (机 械 工 业 出 版 社 出 版 ) 。 


1 .插件 配 置 


在 图 2-4 中 ，integration-test 阶 段 的 前 后 各 有 一 个 扩展 点 pre 和 post，Jetty 播 件 就 是 在 这 两 个 点 启动 和 停止 内 置 的 Jetty 服 务 器 的 。 插 件 配置 (这 是 Jetty 揪 件 早期 的 配置 ， 接 下 来 会 说 明 ) 如 下 。 


<plugin> 
<groupId>org.mortbay.jetty</groupId> 
<artifactId>maven-jetty-plugin</artifactId> 
<version>6.1.26</version> 
<executions> 
<execution> 
<id>start-jetty</id> 
// 


的 pre-integration-test 
生命 周期 执行 zun 
<phase>pre-integration-test</phase> 
<goals> 
<goal>run</goal> 
</goals> 
</execution> 
<execution> 
<id>stop-jetty</id> 


关注 点 2 

: 在 Maven 

的 post-integration-test 

生命 周期 执行 stop 
<phase>post-integration-test</phase> 
<goals> 

<goal>stop</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 


Jetty 的 运行 发 生 在 pre-integration-test 阶 段 ， 见 关注 点 1; Jetty 的 结束 发 生 在 post-integration-test 阶 段 ， 见 关注 点 2。 


读者 在 使 用 Jetty 插 件 时 ， 应 注意 该 插件 的 版 本 信息 。 从 Jetty 7 开始 ，Jetty 的 Maven 插 件 更 改 了 命名 方式 以 适应 Maven 插 件 的 统一 命名 规则 ， 相 应 的 配置 文件 如 下 。 


<plugin> 
<groupId>org.eclipse.jetty</groupId> 


关注 点 1 
: Jetty 
插件 artifactId 
看 
<artifactId>jetty-maven-plugin</artifactId> 
<version>9.1.0.RCO</version> 
<executions> 
<execution> 
<id>start-jetty</id> 
<phase>pre-integration-test</phase> 
<goals> 
<goal>start</goal> 
</goals> 
</execution> 
<execution> 
<id>stop-jetty</id> 
<phase>post-integration-test</phase> 
<goals> 
<goal>stop</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 


从 关注 点 1 可 以 看 到 ，Jetty 揪 件 的 名 称 从 老 版 本 的 maven-jetty-plugin 改 为 jetty-maven-plugin。 
2. 运 行 插件 


可 以 进入 命令 行 ， 在 项 目 根 目录 下 执行 如 下 命令 ， 或 者 在 IDE 中 配置 Maven 使 用 如 下 命令 启动 : 


mvn jetty:run 


Jetty 服 务 器 启动 后 ， 若 要 终止 当前 测试 用 的 Jetty 服 务 器 ， 在 命令 行 可 以 执行 <Ctrl+C> 操 作 ， 在 IDE 中 可 以 停止 Maven 服 务 的 运行 。 


Jetty 服 务 器 启动 后 ， 打 开 浏 览 器 ， 输 入 地 址 : http://localhost:8080/simple-service-webapp， 访 问 Web 服 务 首页 ， 如 图 2-5 所 示 。 


Jersey RESTful Web Application! 


Jersev TesOUTCE 


Visit Project Jersey Website for more inftormation on Jersey! 


图 2-5 ”simple-service-webapp 首 页 


在 图 2-5 中 有 上 下 两 个 链接 :上 面 的 链接 就 是 本 示例 Web 服 务 的 资源 地 址 : http://localhost:8080/simple-service-webapp/webapi/myresource， 单 击 该 链接 会 得 到 资源 类 GET 对 应 方法 ， 该 方法 返 
回 的 字符 串 信 息 是 “Got it! ”。 本 示例 的 WADL 地 址 是 http://localhost:8080/simple-service-webapp/webapi/application.wadl， 关 于 WADL 的 详细 信息 ， 参 见 2.4 节 。 


2.2.3 ”运行 在 Servlet 容 器 


Jetty 插 件 多 用 于 Web 服 务 的 调试 和 集成 测试 ， 在 该 阶段 通过 以 后 ， 通 常会 将 该 项 目 部 署 到 以 Tomcat 为 代表 的 Servlet 容 器 来 搭建 测试 环境 和 运行 环境 。Tomcat 的 安装 、 配 置 和 部 署 实 现 步骤 如 下 。 


1) 从 Tomcat 的 官方 网 址 http://tomcat.apache.org 下 载 Tomcat， 并 解压 缩 到 D 盘 根 目录 。 注 意 ， 读 者 可 以 自行 选择 下 载 版 本 和 本 地 存储 路 径 。 本 例 使 用 的 是 Tomcat 7.0.42， 解 压缩 后 的 目录 为 : 
Di:\apache-tomcat-7.0.42。 


2) 使 用 Maven 命 令 编译 打包 (clean 是 清除 target 目 录 ，package 是 打包 ，-D 是 为 Maven 命 令 设置 运行 时 参数 ，skipTests 参 数 是 忽略 测试 生命 周期 ) 。 


mvn clean package 
-D skipTests=true 


3) 复制 WAR 包 到 Tomcat 应 用 目录 。 


cp target\simple-service-webapp.war D:\apache-tomcat-7.0.42\webapps\simple-service.war 


4) 运行 Tomcat 服 务 器 。 若 要 结束 运行 Tomcat 服 务 器 ， 则 可 以 按 <Ctrl+C> 组 合 键 。 


cd D:\apache-tomcat-7.0.42\bin 
catalina.bat run 


5) 打开 浏览 器 ， 输 入 地 址 : http://localhost:8080/simple-service-webapp 访 问 Web 服 务 首页 。 


其 他 Servlet 容 器 的 部 署 和 运行 类 似 Tomcat， 可 参考 相关 容器 的 文档 ， 这 里 不 再 列举 。 


2.2.4 ”运行 在 Java EE 容器 


同时 ，Web 服 务 可 以 部 署 到 以 GlassFish 为 代表 的 Java EE 容 器 来 搭建 运行 环境 。GlassFish 的 安装 、 配 置 和 部 署 实现 步骤 如 下 。 


1) GlassFish 的 官方 网 址 是 https://glassfishjava.net， 读 者 可 以 自行 选择 下 载 版 本 。 本 例 使 用 的 是 GlassFish 4.0， 解 压缩 后 的 目录 为 : D:\glassfish4。 下 载 地 址 参考 如 下 : 


http://dlc.sun.com.edgesuite.net/glassfish/4.0/release/ glassfish-4.0.zip。 


2) 使 用 Maven 命 令 编译 打包 ， 如 下 所 示 : 


mvn clean package 
-D skipTests=true 


3) 复制 WAR 包 到 GlassFish 默 认 domain 目 录 。 


cp target\simple-service-webapp.war 
D:\glassfish4\glassfish\domains\domainl\autodeploy\simple-service.war 


4) 运行 GlassFish 服 务 器 。 


cd D:\glassfish4\bin 
asadmin start-domain 


5) 打开 浏览 器 ， 输 入 http://localhost:4848 进 入 GlassFish 的 管理 界面 ， 如 图 2-6 所 示 。 
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图 2-6 ”GlassFish 管 理 界面 


在 图 2-6 中 ，REST 服 务 出 现在 GlassFish 管 理 界面 的 应 用 列表 中 。 单 击 “Launch” 启 动 应 用 ， 页 面 自动 跳 转 到 “http:// 主 机 名 :8080/simple-service” 页 面 。 


其 他 Jave EE 容 器 的 配置 和 部 署 类 似 GlassFish， 可 参考 相关 容器 的 文档 。 


到 此 ， 读 者 已 经 掌握 了 开发 基于 JAX-RS 2.0 的 Java SE 应 用 和 REST 式 Web 服 务 的 基本 方法 。 接 下 来 的 一 节 将 讲述 如 何 实现 和 部 署 不 同形 式 的 JAX-RS 2.0 服 务 ， 通 过 这 一 节 的 知识 介绍 ， 读 者 将 掌握 灵活 
实现 一 个 REST 式 Web 服 务 的 技能 。 


2.3 ”REST 服 务 类 型 


通过 前 面 两 节 的 讲述 ， 我 们 对 Jersey 官 方 提供 的 REST 示 例 有 了 基本 了 解 ， 并 初步 掌握 如 何 从 头 编写 一 个 REST 服 务 。 在 REST 服 务 中， 资源 类 是 接收 REST 请 求 并 完成 响应 的 核心 类 ， 而 资源 类 是 由 REST 服 
务 的 “提供 者 ”来 调度 的 。 这 一 概念 类 似 其 他 框架 中 自 定义 的 Servlet 类 ， 该 类 会 将 请 求 分 派 给 指定 的 Controller/Action 类 来 处 理 。 本 节 将 讲述 REST 中 的 这 个 提供 者 ， 即 JAX-RS 2.0 中 定义 的 Application 以 


及 Servlet。 


Application 类 在 JAX-RS 2.0 (JSR 339， 详 见 参考 资料 ) 标准 中 定义 为 javax.ws.rs.core.Application， 相 当 于 JAX-RS 2.0 服 务 的 入 口 。 作 为 应 用 的 入 口 ，Application 需 要 知道 具体 的 资源 文件 ， 这 里 可 
以 通过 包 扫 描 或 直接 指定 类 文件 的 方式 获得 。 如 果 REST 服 务 没有 自 定义 Application 的 子 类 ， 容 器 将 默认 生成 一 个 javax.ws.rs.core.Application 类 。 


本 节 根 据 JAX-RS 2.0 规 范 上 文中 对 REST 服 务 场景 的 定义 ， 将 REST 服 务 分 为 4 种 类 型 ， 如 图 2-7 所 示 。 


存在 Application 子 : 


图 2-7 REST 服 务 类 型 示意 图 


到 2-7 将 JAX-RS 2.0 标 准 中 对 REST 服 务 的 类 型 图 形 化 ， 依 据 不 同 的 条 件 分 为 了 4 种 类 型 。 


类 型 一 : 当 服 务 中 没有 Application 子 类 时 ， 容 器 会 查找 Servlet 的 子 类 来 做 入 口 ， 如 果 Servlet 的 子 类 也 不 存在 ， 则 REST 服 务 类 型 为 类 型 一 ， 对 应 图 2-7 中 的 例 1。 


类 型 二 : 当 服务 中 没有 Application 子 类 ， 但 存在 Servlet 的 子 类 时 ， 则 REST 服 务 类 型 为 类 型 二 ， 对 应 图 2-7 中 的 例 2。 


类 型 三 : 服务 中 定义 了 Application 的 子 类 ， 而 且 这 个 Application 的 子 类 使 用 了 @ApplicationPath 注 解 ， 则 REST 服 务 类 型 为 类 型 三 ， 对 应 图 2-7 中 的 例 3。 


类 型 四 : 如 果 服 务 中 定义 了 Application 的 子 类 ， 但 是 这 个 Application 的 子 类 没有 使 用 @ApplicationPath 注 解 ， 则 REST 服 务 类 型 为 类 型 四 ， 对 应 图 2-7 中 的 例 4。 


上 面 提 到 的 4 个 示例 在 下 面 的 “阅读 指南 ”中 给 出 了 源 代码 目录 和 GitHub 下 载 地 址 ， 需 要 读者 仔细 体会 示例 之 间 的 差异 ， 以 更 好 地 理解 和 使 用 不 同类 型 的 REST 服 务 。 


1.REST 服 务 类 型 一 


类 型 一 对 应 的 是 图 2-7 中 所 示 的 例 1， 相 应 的 逻辑 是 服务 中 同时 不 存在 Application 的 子 类 和 Servlet 的 子 类 。 在 JAX-RS 2.0 (JSR 339) 中 定义 在 这 种 情况 下 应 进行 如 下 处 理 : 为 REST 服 务 动态 生成 一 个 名 


为 javax.ws.rs.core.Application 的 Servlet 实 例 ， 并 自动 探测 匹配 资源 。 与 此 同时 ， 需 要 根据 Servlet 的 不 同 版 本 ， 在 web.xml 定 义 REST 请 求 处 理 的 Servlet 为 这 个 动态 生成 的 Servlet， 并 定义 该 Servlet 对 资源 
路 径 的 匹配 。 在 没有 Application 的 子 类 存在 的 情况 下 ， 在 web.xml 中 定义 Servlet 是 必 不 可 少 的 配置 。 


人 @@ 阅 读 指南 REST 服 务 关 型 一 所 对 应 的 示例 ， 即 例 1 所 在 目录 是 : 
1) jax-rs2-guide\sample\2\1simple-service-webapp-servlet2-webxml 
2) jax-rs2-guide\sample\2\1simple-service-webapp-servlet3-webxml 
源 代码 地 址 : 


1) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/1simple-service-webapp-servlet2-webxml 


2) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/1simple-service-webapp-servlet3-webxml 


REST 服 务 类 型 一 的 示例 包含 两 个 小 项 目 ， 分 别 对 应 Servlet 2 和 Servlet 3 两 种 容器 依赖 场景 。 我 们 只 需 关 注 Maven 配 置 文件 (pom.xml) 和 Web 服 务 配置 文件 (web.xml) 的 区 别 即 可 理解 存在 无 
Application 子 类 的 情况 下 ， 如 何 实现 基于 Servlet 2 和 Servlet 3 容器 内 的 服务 。 


Servlet 3 的 最 简 配 置 示例 代码 如 下 。 


<?xml Version="1.0" encoding="UTF-8"?> 
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/Java EE" 
xmlns:xsi=http://www.w3.0org/2001/XMLSchema-instance 
xsi:schemaLocation="http://java.sun.com/xml/ns/Java EE http://java.sun.com/xml/ns/Java 
EE/web-app 3 0.xsd"> 
<servlet> 
<servlet-name>javax.ws.rs.core.Application</servlet-name> 
</servlet> 
<servlet -mapping> 
<servlet-name>javax.ws.rs.core.Application</servlet-name> 
<url-pattern>/webapi/*</url-pattern> 
</servlet-mapping> 
</web-app> 


相对 于 Servlet 2 而 言 ， 在 Servlet 3 中 ，Servlet 的 定义 可 以 只 包含 servlet-name。 再 次 强调 ，Jersey 的 Servlet 3 的 容器 支持 包 是 jersey-container-servlet。 


Servlet 2 的 最 简 配 置 示例 代码 如 下 。 


<?xml version="1.0" encoding="UTF-8"?> 
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/Java EE" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/Java EE http://java.sun.com/xml/ns/Java 
EE/web-app 2 5.xsd"> 
<servlet> 
<servlet-name>Jersey Web Application</servlet-name> 
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
<init-param> 
<param-name>jersey .config.server.provider.packages</param-name> 
<param-value>com.example</param-value> 
</init-param> 
<load-on-startup>1</1l0ad-on-startup> 
</servlet> 
<servlet-mapping> 
<servlet-name>Jersey Web Application</servlet-name> 
<url-pattern>/webapi/*</url-pattern> 
</servlet-mapping> 
</web-app> 


Servlet 的 定义 包含 servlet-name 和 servlet-class， 其 初始 化 参数 需要 显示 给 出 要 加 载 的 资源 类 所 在 的 包 名 ， 可 以 看 出 Servlet 2 的 支持 包 jersey-container-servlet-core 不 具备 自动 扫描 资源 类 的 功能 。 


2.REST 服 务 类 型 二 


类 型 二 对 应 的 是 


网 


2-7 中 所 示 的 例 2， 相 应 的 逻辑 是 不 存在 Application 的 子 类 但 存在 Servlet 的 子 类 。 


人 阅读 指南 REST 服 务 类 型 二 对 应 的 示例 所 在 目录 是 : 


jax-rs2-guide\sample\2\2simple-service-webapp-subservlet 


源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/2simple-service-webapp-subservlet 


本 例 定义 了 Servlet 子 类 AirServlet， 该 类 继承 自 org.glassfish.jersey.servlet.ServletContainer 类 ， 这 是 Jersey 2 中 Servlet 的 基 类 ， 继 承 自 HttpServlet。AirServlet 类 的 代码 示例 如 下 。 


QWebServlet( 

initParams = @WebInitParam( 

name = "jersey.config.server.provider.packages", value = "com.example"), 
urlPatterns = "/webapi/*", 

loadonstartup = 1) 

public class AirServlet extends ServletContainer { 


AirServlet 使 用 了 WebServlet 注 解 来 配置 Servlet 参 数 。 包 括 初始 化 参数 initParams 中 定义 扫描 的 资源 类 所 在 的 包 名 : “com.example”，Servlet 匹 配 的 资源 路 径 : urlPatterns=“/webapi/*” 和 
时 的 加 载 标识 : loadOnStartup=1。 


例 2 是 基于 Servlet 3 容器 的 REST 服 务 ， 使 用 了 Webservlet 注 解 和 无 web.xml 等 Servlet 3 引入 而 Servlet 2 没有 的 功能 。 在 自 定义 Servlet 3.x 子 类 的 场景 下 ，web.xml 可 以 省 略 ， 但 需要 修改 Maven 的 
maven-war-plugin 插 件 的 配置 ， 添 加 failonMissingWebXm| 为 false， 这 样 编译 时 才 不 会 报错 。Maven 配 置 文件 中 相关 信息 如 下 所 示 。 


<plugin> 
<groupId>org.apache.maven.plugins</groupId> 
<artifactId>maven-war-plugin</artifactId> 
<version>2.3</version> 
<configuration> 

<failOnMissingWebxml>false</failOnMissingWebxml> 

</configuration> 

</plugin> 

<dependency> 
<groupId>javax.servlet</groupId> 
<artifactId>javax.servlet-api</artifactId> 
<version>3.1.0</version> 
<scope>provided</scope> 

</dependency> 


3.REST 服 务 类 型 三 


类 型 三 对 应 的 是 


网 


2-7 中 所 示 的 例 3， 相 应 的 逻辑 是 存在 Application 的 子 类 并 且 定 义 了 @ApplicationPath 注 解 。 


全 阅读 指南 “REST 服 务 关 型 三 对 应 的 示例 所 在 目录 是 : 
1) jax-rs2-guide\sample\2\3simple-service-webapp-servlet2-rc 
2) jax-rs2-guide\sample\2\3simple-service-webapp-servlet3-application 


源 代码 地 址 : 


启动 


1) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/3simple-service-webapp-servlet3-application 


2) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/3simple-service-webapp-servlet2-rc 


REST 服 务 类 型 三 的 示例 包含 两 个 小 项 目 。 其 中 ，servlet2-rc 项 目 基于 Servlet 2，AirResource-Config 类 继承 自 Application 的 子 类 ResourceConfig 类 ; servlet3-application 项 目 基于 Servlet 
3，AirApplication 类 继承 自 Application 类 。 基 于 Servlet 2 的 REST 服 务 需要 定义 web.xml (但 内 容 可 以 是 “ 空 的 ”， 即 只 有 web-app 的 基本 定义 ) ， 基 于 Servlet 3 的 REST 服 务 可 以 省 略 此 文件 。 


AirApplication 类 代码 示例 如 下 。 


@ApplicationPath ("/webapi/*") 
public class AirApplication extends Application { 
QOverride 
public Set<Class<?>> getClasses() { 
final Set<Class<?>> classes = new HashSet<Class<?>>(); 
classes.add (MyResource.class); 
return classes; 


AirApplication 类 覆盖 了 getClasses() 方 法 ， 注 册 了 资源 类 MyResource， 这 样 在 服务 启动 后 ，MyResource 类 提供 的 资源 路 径 将 被 映射 到 内 存 ， 以 便 请 求 处 理 时 匹配 相关 的 资源 类 和 方法 。 


AirResourceConfig 类 代码 示例 如 下 。 


@ApplicationPath 
("/webapi/*" 
) 


public class AirResourceConfig extends ResourceConfig { 
public AirResourceConfig() { 
packages 
("com.example" 
); 
. 
} 


AirResourceConfig 类 在 构造 子 中 提供 了 扫描 包 的 全 名 ， 这 样 在 服务 启动 后 ，“com.example” 包 内 资源 类 所 提供 的 资源 路 径 将 被 映射 到 内 存 。 


4.REST 服 务 类 型 四 


类 型 四 对 应 的 是 图 2-7 中 所 示 的 例 4， 相 应 的 逻辑 是 “一 有 二 无 ”: 一 有 是 存在 Application 的 子 类 ; 二 无 是 不 存在 Servlet 子 类 、 不 存在 或 者 不 允许 使 用 注解 @ApplicationPath。 


全 阅 诸 旧 南 REST 服 务 类型 四 对 应 的 示例 所 在 目录 是 : 

1) jax-rs2-guide\sample\2\4simple-service-webapp-servlet2-application 

2) jax-rs2-guide\sample\2\4simple-service-webapp-servlet3-application 

源 代码 地 址 : 

1) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/4simple-service-webapp-servlet2-application 


2) https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/4simple-service-webapp-servlet3-application 


REST 服 务 类 型 四 的 示例 包含 两 个 小 项 目 ， 演 示 了 基于 Servlet 2 和 Servlet 3 两 个 版 本 的 REST 服 务 ， 
说 明 。 


其 差异 仅 此 而 已 ， 关 于 差异 性 配置 前 面 的 例子 已 经 讲 过 ， 不 再 元 述 。 下 面 以 servlet3-application 为 例 


AirApplication 类 是 Application 的 子 类 ， 代 码 示例 如 下 。 


public class AirApplication extends Application { 
QOverride 
public Set<Class<?>> getClasses() { 
final Set<Class<?>> classes = new HashSet<Class<?>>(); 
classes.add (MyResource.class); 
return classes; 


上 述 代码 和 类 型 三 的 示例 相仿 ， 但 是 该 类 没有 定义 @ApplicationPath 注 解 ， 因 此 我 们 需要 在 web.xml 中 配置 Servlet 和 映射 资源 路 径 。 其 代码 示例 如 下 。 


<?xml Version="1.0" encoding="UTF-8"?> 
<web-app xmlns="http://java.sun.com/xml/ns/Java EE" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation= 
"http://java.sun.com/xml/ns/Java EE http://java.sun.com/xml/ns/Java FE/ 
web-app_3 0.xsd" version="3.0"> 
<servlet> 
<servlet-name>com.example.AirApplication</servlet-name> 
</servlet> 
<servlet -mapping> 
<servlet-name>com.example.AirApplication</servlet-name> 
<url-pattern>/webapi/*</url-pattern> 
</servlet-mapping> 
</web-app> 


在 servlet-name 中 使 用 自 定义 的 Application 子 类 com.example.AirApplication 的 全 名 作为 Servlet 名 称 ， 并 在 url-pattern 中 映射 资源 路 径 。 


2.4 ”REST 应 用 描述 


在 明白 如 何 创建 和 部 署 各 种 类 型 的 REST 服 务 后 ， 我 们 来 了 解 一 下 部 团 好 的 REST 服 务 中 的 一 个 特殊 的 成 员 一 一 REST 应 用 的 描述 : 以 XML 格 式 展示 当前 REST 环 境 中 所 提供 的 REST 服 务 接口 。 这 种 XML 格 
式 的 描述 就 是 WADL。 


WADL (Web Application Description Language，Web 应 用 描述 语言 ) 是 用 来 描述 基于 HTTP 的 REST 式 Web 服 务 部 署 情 况 的 。 它 采用 XML 格 式 ， 支 持 多 种 数据 类 型 的 描述 。WADL 由 Sun 公 司 提出 ， 
尚未 成 为 W3C 或 者 OASIS 的 标准 ，JAX-RS 标 准 中 并 没有 关于 WADL 的 定义 和 说 明 。Jersey 作 为 JAX-RS 2.0 的 参考 实现 ， 默 认 支 持 服务 的 WADL。 通 过 浏览 器 访问 “服务 根 路 径 /application.wadl” 即 可 打开 
该 服务 的 WADL 内 容 。 相 对 于 WADL，WSDL 更 为 人 们 所 熟知 ，WSDL 是 RPC 风 格 的 基于 SOAP 的 Web 服 务 的 描述 语言 。 两 者 缩写 类 似 而 且 都 使 用 XML 格式 ， 此 外 共性 不 多 。 


2.4.1 ”应 用 的 描述 


以 2.3 节 的 REST 服 务 类 型 四 的 示例 项 目 simple-service-webapp-servlet3-application 为 例 ， 该 应 用 的 WADL 路 径 如 下 : 


http:/ /localhost:8080/simple-service-webapp-servlet3-application/webapi/application.wadl 


加 


通过 浏览 器 访问 该 路 径 ， 可 以 浏览 WADL 的 schema 结 构 。WADL 的 最 外 层 标 签 是 application， 代 表 应 用 。 然 后 自 上 而 下 分 别 是 doc、grammars 和 resources。resources 是 应 用 提供 的 资源 集合 ， 生 
至 少 包 含 application.wadl， 以 及 应 用 中 包含 的 资源 描述 ， 比 如 本 例 的 资源 信息 描述 在 资源 路 径 myresource 之 内 ， 如 下 所 示 。 


<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<application> 
<doc jersey:generatedBy="Jersey: 2.3 2013-09-20 13:59:07"/> 
<grammars/> 
<resources 
base="http://localhost:8080/simple-service-webapp-servlet3-application/webapi/"> 
<resource path="myresource">http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/O0EBPS/Text/...</resource> 
<resource path="application.wadl">http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/...</resource> 
</resources> 
</application> 


2.4.2 ”资源 的 描述 


可 以 展开 myresource 来 查看 具体 某 个 方法 的 NADL， 也 可 以 通过 发 送 一 条 请 求 并 定义 请 求 头 信息 来 获取 。 以 cURL (该 工具 的 介绍 见 2.6.1 节 ) 为 例 ， 命 令 为 : 


Curl -X OPTIONS -H "Allow: application/vnd.sun.wadl+xml" -v 
http://localhost:8080/simple-service-webapp-servlet3-application/webapi/myresource 


REST 服 务 类 型 四 的 示例 项 目 simple-service-webapp-servlet3-application 提 供 的 资源 接口 ， 对 照 服务 器 返回 的 XML， 可 以 更 加 清晰 地 理解 WADL 的 内 容 。 其 WADL 内 容 如 下 所 示 。 


<resource path="myresource"> 
<method id="getIt" name="GET"> 
<response> 
<representation mediaType="text/plain"/> 
</response> 
</method> 
<method id="apply" name="OPTIONS"> 
<request> 
<representation mediaType="*/*"/> 
</request> 
<response> 
<representation mediaType="application/vnd.sun.wadlt+xml"/> 
</response> 
</method> 
<method id="apply" name="OPTIONS"> 
<request> 
<representation mediaType="*/*"/> 
</request> 
<response> 
<representation mediaType="text/plain"/> 
</response> 
</method> 
<method id="apply" name="OPTIONS"> 
<request> 
<representation mediaType="*/*"/> 
</request> 
<response> 
<representation mediaType="*/*"/> 
</response> 
</method> 
</resource> 


在 这 段 代码 中 ， 公 布 了 4 个 方法 。 其 中 ，getlt() 方 法 代码 如 下 。 
型 。 


他 3 个 OPTIONS 请 求 方法 是 Jersey 默 认 实现 的 ， 用 以 描述 getlt() 方 法 ， 分 别 返 回 text/plain 类 型 、application/vnd.sun.wadl+xml 类 


@GET 

Q@Produces 
(MediaType.TEXT PLAIN 

) 


public String getIt() { 
return "Got it!"; 


} 


getlt0 方 法 定义 为 GET 请 求 方 法 ，@Produces 中 定义 的 媒体 类 型 是 MediaType.TEXT_PLAIN， 即 响应 过 程 中 生产 的 数据 ， 其 表述 性 状态 以 text/plain 媒 体 类 型 转移 。 


2.4.3 WADL 的 配置 


上 述 OPTIONS 请 求 方法 的 实现 是 Jersey 默 认 支 持 的 ， 如 果 读 者 不 希望 在 REST 服 务 中 让 Jersey 自 动 生 成 ， 可 以 通过 配置 jersey.config.serverwadl.disableWadl=true 来 实现 。 代 码 示例 如 下 。 


public class AirApplication extends ResourceConfig { 
public AirApplication() { 
property 
(ServerProperties.WADL FEATURE DISABLE, true 
); 
packages 
("com.example.resource" 


} 


在 构造 函数 中 ， 我 们 通过 定义 ServerProperties.WADL_FEATURE_DISABLE 属 性 为 true 实 现 去 WADL 自 动 生成 的 功能 。 


或 者 ， 可 以 通过 修改 Web 配 置 文件 中 servlet 启 动 参数 来 实现 ， 代 码 示例 如 下 。 


<servlet> 
<servlet-name>com.example.AirApplication</servlet-name> 
<init-param> 
<param-name>jersey.config.server.wadl .disableWadl</param-name> 
<param-value>true</param-value> 
</init-param> 
</servlet> 


配置 文件 中 定义 了 启动 参数 jersey.config.server.wadl.disableWadl， 其 值 定义 为 true， 以 实现 去 WADL 自 动 生成 的 功能 。 


有 关 Jersey 的 配置 详情 和 示例 ， 读 者 可 参考 本 书 的 10.3 节 。 


2.5 第 一 个 完整 的 REST 服 务 


通过 本 章 前 面 4 节 的 讲述 ， 我 们 已 经 知道 如 何 为 使 用 不 同 的 配置 ， 在 不 同 的 环境 下 使 用 Jersey 实 现 REST 式 的 Web 服 务 了 。 但 前 面 的 示例 不 够 完整 ， 在 快速 实现 的 学 习 阶段 ， 读 者 最 希望 看 到 的 是 一 个 完 
整 的 服务 。 本 节 将 结合 Spring、JPA 和 jQuery， 展 示 一 个 完整 的 REST 式 的 Web 服 务 ， 该 服务 用 来 完成 对 图 书 资源 的 存 取 。 


图 阅读 指南 2.5 节 示例 所 在 目录 是 : jax-rs2-guide\sample\2\5simple-service-webapp-spring-jpa-jquery。 
源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/5simple-service-webapp-spring-jpa-jquery。 


实体 部 分 抽象 到 通用 模块 中 ， 所 在 目录 是 : jax-rs2-guide\sample\common。 


作为 示例 ， 本 节 定 义 的 资源 的 实体 相对 简单 ， 只 有 一 个 图 书 实体 。 更 复杂 的 示例 可 参考 第 11 章 的 综合 示例 。 


REST 服 务 的 核心 是 对 外 公布 的 资源 API。 定 义 资源 通常 包括 资源 实体 及 其 表述 的 设计 、 资 源 路 径 的 定义 ， 最 后 是 使 用 JAX-RS 2.0 对 定义 好 的 资源 API 进 行 编码 实现 。 在 本 例 中 ， 我 们 要 定义 并 发 布 图 书 资 
源 存 取 的 REST 服 务 。 


因此 ， 资 源 定义 包括 以 下 几 个 方面 : 


书 实体 类 的 定义 。 


“ 资源 路 径 的 设计 。 


“ 通过 图 书 资源 类 实现 图 书 资源 存 取 服 务 。 


1. 图 书 实 体 类 


键 、 图 书 名 称 和 出 版 人 。 示 例 代 码 如 下 。 


首先 定义 图 书 资源 的 实体 类 ， 最 简 的 图 书 类 应 包括 3 


@XmlRootElement 

public class Book{ 
private Long bookId; 
private String bookName; 
Private String publisher; 


Book 类 是 一 个 简单 的 POJO， 使 用 了 JAXB 的 注解 @XmlRootElement， 以 实现 XML 和 POJO 之 间 的 转换 。@XmlRootElement 标 识 Book 作 为 XML 结构 的 根 元 素 。Book 类 包含 一 个 长 整 型 的 主键 字段 
bookld、 一 个 字符 串 型 的 图 书 名 称 字 段 bookName 和 一 个 字符 串 类 型 的 出 版 社 字段 publisher。 


2. 资 源 路 径 


有 了 图 书 实体 类 ， 接 下 来 根据 业务 为 其 定义 资源 路 径 ， 以 对 外 提供 REST 服 务 。 图 书 资源 路 径 见 表 2-1。 


表 2-1 图 书 资源 路 径 列 表 


资源 路 径 输出 
/books/{bookId:[0-9]*} | ”通过 主键 获取 指定 图 书 资源 Book 对 象 
/books/book?id=… 通过 主键 获取 指定 图 书 资源 [GET |id | Book 对 象 
/books 新 增 图 书 资源 Book 对 象 
/books/{bookId:[0-9]*} | ”通过 主键 更 新 指定 图 书 资源 Book 对 象 


/books/{bookId:[0-9]*} | ”通过 主键 删除 指定 图 书 资源 删除 结果 字符 串 


表 2-1 列 出 了 最 基本 的 资源 存 取 功 能 ， 其 中 定义 了 3 个 查询 接口 ， 包 括 查询 全 部 图 书 资源 接口 和 根据 主键 ID 查询 指定 图 书 资源 的 两 种 形式 的 接口 ， 写 入 接口 包括 增加 图 书 、 根 据 主键 删除 和 修改 图 书 等 3 
个 接口 。 在 资源 路 径 的 绑 定 定义 中 ， 可 以 使 用 正则 表达 式 ， 详 情 见 3.2 节 。 


bb | 一 


在 增加 、 删 除 、 修 改 、 查 询 的 REST 接 口 定 义 中 ， 新 增 和 修改 功能 该 使 用 POST 还 是 PUT， 意 见 并 不 统一 。 笔 者 秉持 的 是 ROA 风 格 ， 修 改 使 用 PUT 方法 ， 新 增 使 用 POST 方法 。 这 看 似 字面 略 有 不 同 的 定义 
背后 ， 是 对 REST 式 的 Web 服 务 的 正确 解读 。 定 义 资源 路 径 就 是 设计 REST 接 口 的 过 程 ， 一 方面 需要 对 业务 有 深刻 的 理解 ， 另 一 方面 需要 对 REST 风 格 有 真知 灼 见 。3.1 节 将 着 重 讲述 REST 风 格 的 API 设 计 。 


的 POJO。 示 例 代 码 如 下 。 


REST 接 口 的 实体 类 定义 中 ， 要 考虑 集合 数据 的 处 理 。 本 例 对 Book 类 的 集合 封装 了 Books 类 ， 用 来 专门 作为 返回 值 使 


Q@XmlRootElement 
(name = "books" 
) 
public class Books implements Serializable { 
private List<Book> bookList; 
@XxmlElement 
(name = "book" 


) 
// 
关注 点 1 
: JAXB 
包装 元 素 
@xmlElementWrapper 
public List<Book> getBookList() { 


return bookList; 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代码 中 ，Books 类 是 Book 的 集合 类 型 ， 以 集合 封装 一 类 资源 ， 其 结果 集 逻 辑 清晰 、 结 构 工 整 。 值得 注意 的 是 @XmlElementWrapper 注 解 的 使 用 ， 见 关注 点 1。 在 包装 了 一 层 books 集 合 后 ， 所 得 


ba 
网 


书 资源 类 


到 的 XML 或 者 JSON 格 式 的 数据 将 多 一 层 封装 。 这 在 Web 页 面 泻 染 解析 时 ， 需 要 谨慎 编写 相关 的 处 理 脚本 。 


接 下 来 是 图 书 资源 类 BookResource， 该 类 是 对 上 述 设计 的 具体 实现 。 和 本 章 前 述 示例 相同 的 是 使 用 @Path、@GET 等 注解 绑 定 资源 路 径 和 资源 方法 ， 本 例 较 本 章 前 面 的 例子 更 完整 ， 引 入 了 逻辑 中 间 


书 资源 类 BookResource 定 义 如 下 。 


[ 


@Path ("books") 
public class BookResource { 


private static final Logger LOGGER = Logger.getLogger (BookResource.class); 


a 
关注 点 1 
: Service 
实例 用 于 处 理 业务 逻辑 
@Autowired 
private BookService bookService; 
Q@GET 
@Produces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Books getBooks() { 加 
final Books books = bookService.getBooks(); 
BookResource .LOGGER. debug (books); 
return books; 


} 
@Path ("{bookId: [0-9] *}") 
@GET 
Q@Produces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Book getBookByPath (@PathParam("bookId") final Long bookId) { 
final Book book = bookService.getBook (bookId); 
BookResource .LOGGER. debug (book); 
return book; 
} 
@Path ("/book") 
@GET 
@Produces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Book getBookByQuery (@QueryParam("id") final Long bookId) { 
final Book book = bookService.getBook (bookId); 
BookResource .LOGGER. debug (book); 
return book; 


} 
@POST 
@Produces ({MediaType .APPLICATION JSON, MediaType.APPLICATION XML}) 
@Consumes ( {MediaType .APPLICATION JSON, 
MediaType.APPLICATION XML, MediaType.TEXT XML}) 
public Book saveBook (final Book book) { 
return bookService.saveBook (book); 


} 

@Path (" {bookId: [0-9]*}") 

@PUT 

QProduces ( {MediaType .APPLICATION JSON, MediaType.APPLICATION XML}) 


Q@Consumes ( {MediaType .APPLICATION JSON, MediaType.APPLICATION XML, MediaType.TEXT XML)}) 
Public Book updateBook (@PathParam("bookId") final Long bookId, final Book book) { 


if (book == null) { 
return null; 
} 
return bookService.updateBook (bookId, book); 
} 
@Path ("/{bookId: [0-9] *}") 
@DELETE 
public String deleteBook (@PathParam ("bookId") final Long bookId) { 
if (bookService.deleteBook(bookId)) { 
return "Deleted book id=" + bookId; 
} else { 
return "Deleted book failed id=" + bookId; 
} 


方法 中 ， 具 体 业务 罗 辑 由 使 


从 上 面 的 代码 片段 中 可 以 看 出 ， 资 源 类 BookResource 实 现 了 设计 中 定义 的 6 个 接口 ， 分 别处 理 图 书 资源 的 查询 和 写 入 。 根 据 HTTP 请 求 方法 和 URI 分 派 到 匹配 的 方法 ， 并 将 方法 的 处 理 结果 返回 。 在 每 个 


容器 是 HK2， 因 此 集成 Spring 需要 扩展 包 才 能 实现 。 


2.5.2 ”集成 Spring 


Spring 作为 轻 量 级 Java EE 开 发 框架 ， 降 低 了 中 间 件 和 逻辑 层 的 开发 难度 ， 提 升 了 开发 效率 。 结 合 Spring， 可 以 轻松 实现 事务 、Bean 的 容器 管理 ， 以 及 面向 切面 的 需求 。 


与 Spring 集成 。 


(1) 定义 依赖 包 


Jersey 对 Spring 的 依赖 定义 如 下 所 示 。 


<dependency> 
<groupId>org.glassfish.jersey.ext</groupId> 
<artifactId>jersey-spring3</artifactId> 
<version>$ {jersey.version}</version> 
</dependency> 


org.glassfish.jersey.ext 这 个 包 名 是 为 Jersey 扩 展 功能 所 使 用 的 。1.4 节 曾经 介绍 过 


Spring， 使 用 的 Jersey 版 本 不 要 小 于 2.2。 


(2) 使 用 依赖 注入 


@Autowired 注 解 的 业务 逻辑 类 BookService 来 处 理 ， 见 关注 点 1。@Autowired 是 Spring 的 loC 容 器 自动 探测 Bean 实 例 所 使 用 的 注解 。 需 


要 注意 的 是 ，Jersey 内 部 使 用 的 loC 


加 


此 ， 本 节 将 介绍 Jersey 如 何 


Jersey 的 扩展 包 jersey-spring3， 该 扩展 包 是 从 Jersey 2.2 开 始 随 Jersey 2.x 发 布 的 ， 因 此 ， 需 要 注意 的 是 ， 如 果 要 集成 


定义 好 依赖 包 ， 我 们 就 可 以 在 当前 项 目 中 使 用 Spring 的 特性 了 。BookResource 类 中 使 用 的 @Autowired 注 解 的 


QService 

public class BookService { 

@Path ("books") 

public class BookResource { 
@Autowired 
Private BookService bookService; 


书 逻 辑 类 BookService 定 义 如 下 所 示 。 


BookService 类 使 用 了 Spring 的 @Service 注 解 ， 表 示 该 类 是 一 种 作为 服务 的 组 件 


(@Component) 。 


和 Jersey 的 注册 或 者 扫描 类 路 径 相 似 ，Spring 的 loC 是 通过 配置 文件 来 定义 的 。Spring 的 配置 文件 默认 路 径 和 名 称 为 : src\main\resources\applicationContext.xml。 和 容器 管理 Bean 相 关 的 配置 如 下 


所 示 。 


<context:component-scan base-package="com.example" /> 


这 一 行 配置 的 作用 是 ， 当 系统 启动 时 ，Spring 会 根据 该 配置 扫描 com.example 路 径 下 所 有 类 ， 将 注解 为 @component 的 类 以 及 注解 为 @Service 这 样 的 本 身 使 用 了 @component 注 解 的 类 加 载 。 


(3) 面向 切面 的 事务 管理 


集成 Spring 的 一 个 优点 是 可 以 将 数据 库 事务 管理 交 给 容器 。 需 要 注意 的 是 ，JPA 的 写 操作 需要 显 式 地 提交 事务 ， 如 果 不 通 过 容器 管理 事务 ， 就 得 在 每 个 写 操作 的 代码 块 中 ， 加 入 事务 管理 的 代码 ， 这 样 
的 模板 代码 显然 是 开发 者 不 喜欢 编写 和 阅读 的 。 使 用 Spring 后 ， 在 其 配置 文件 applicationContext.xml 中 使 用 一 行 XML 配置 ， 即 可 定义 统一 的 容器 管理 事务 功能 。 示 例如 下 。 


<tx:annotation-driven transaction-manager="transactionManager" /> 

<bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager"> 
<property name="entityManagerFactory" ref="entityManagerFactory" /> 

</bean> 


这 里 用 到 了 transactionManager， 这 是 面向 切面 进行 事务 管理 实例 ， 其 内 部 与 JPA 工 厂 类 相连 ， 为 Spring 容器 提供 了 数据 库 访问 切面 的 控制 管理 能 力 。 


在 写 操作 的 方法 上 使 用 注解 @Transactional 即 可 实现 容器 级 别 的 AOP 事 务 处 理 。 示 例 代码 如 下 : 


QTransactional 

public void save 

(final Book entity 

4 
entityManager.persist 

(entity 


} 


pu 


save() 方 法 在 开始 执行 前 ，Spring 容 器 会 启用 事务 的 begin 方 法 ， 在 save() 方 法 成 功 执行 后 ，Spring 容 器 会 commit 该 事务 ， 否 则 rollback 该 事务 。 


(4) 集成 测试 


在 完成 了 对 Spring 的 集成 后 ， 我 们 要 为 各 个 类 写 单 元 测试 代码 。 那 么 如 何在 测试 中 保持 Spring 容器 的 存在 性 呢 ? 示例 如 下 。 


@ContextConfiguration (locations = { "classpath:applicationContext.xml" }) 

@RunWith (SpringJUnit4ClassRunner.class) 

public class TUMyServiceTest { 

http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 


集成 测试 代码 使 用 @RunWith 注 解 利用 Spring 的 SpringJUnit4ClassRunner 类 ， 使 JUnit 测 试 环境 具备 Spring 容器 的 功能 ， 可 以 在 单元 测试 和 集成 测试 中 模拟 Spring 容器 生产 环境 的 场景 。 


2.5.3 ”集成 JPA 


JPA 2.1 是 Java EE 7 的 标准 之 一 ， 本 例 使 用 的 JPA 是 其 参考 实现 EclipseLink。 数 据 库 驱动 使 用 MySQL 5.1。 


1.JPA 2.1 配 置 


JPA 2.1 的 配置 默认 使 用 src\mainN\resourcesS\META-INF\persistence.xml 文 件 。 示 例 代 码 如 下 。 


<persistence-unit name="jpaMysql" transaction-type="RESOURCE LOCAL"> 
<!-— provider --> 
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> 
eo 
关注 点 1 
: 实体 类 定义 
<class>com.example.domain.Book</class> 
<!-- Connection JDBC --> 
<properties> 
En 
关注 点 2 
: JPA 
配置 
<property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/> 
<property name="javax.persistence.jdbc.url" 
value="jdbc:mysql://localhost:3306/simple service book"/> 
<property name="javax.persistence.jdbc.user" value="root"/> 
<property name="javax.persistence.jdbc.password" value="root"/> 
<!--<property name="eclipselink.ddl-generation" value="create-tables"/> --> 
</properties> 
</persistence-unit> 


上 述 配置 中 定义 了 实体 类 com.example.domain.Book， 该 类 将 对 应 数据 库 的 “simple_book” 表 ， 见 关注 点 1。 数 据 库 JDBC 的 配置 均 使 用 javax.persistence 前 缀 作为 属性 的 键 值 ， 这 是 标准 的 JPA 有 别 
于 使 用 Hibernate 的 地 方 ， 见 关注 点 2。 


2 数据 表 实体 类 


数据 表 的 实体 类 用 于 将 POJO 和 数据 库 的 表 进 行 一 一 映射 。 示 例 代码 如 下 。 


// 


关注 点 1 

: 实体 注解 

@Entity 

@Table 

(name = "simple book" 
) 


public class Book implements Serializable { 
private Long bookId; 
Private String bookName; 
Private String publisher; 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach_ebook/uncompressed/14898/OFEBPSVText/... 


// 
关注 点 2 
: 主键 注解 

QId 

Q@GeneratedValue 
(strategy = GenerationType.IDENTITY, generator = "EMP_ SEQ" 
) 


Q@SequenceGenerator 
(name = "EMP_SEQ" 


) 

Q@Column 
《unique = true, nullable = false, name = "BOOKID" 
) 


public Long getBookId() { 
return bookId; 


(length = Book.NAME LENGTH, name = "BOOKNAME" 
bp 


Public String getBookName () { 
return bookName; 
} 
@Colummn 
(length = Book.NAME LENGTH, name = "PUBLISHER" 
) 3 


public String getPublisher() { 
return publisher; 


实体 类 Book 使 用 JPA 的 注解 @Entity 和 @Table (name="simple_book") ， 使 Object 和 Relationship 的 数据 库 表 映射 起 来 ， 见 关注 点 1。 主 键 使 


@Column 注 解 的 length 参 数 来 定义 ， 字 段 名 称 通 过 @ Column 注 解 的 Name 来 定义 ， 见 关注 点 2 和 关注 点 3。 


3.MySQL 配 置 


本 例 使 


MySQL 5.6.1，UTF8 字 符 集 ， 配 置 如 下 所 示 。 


数据 库 的 Sequence 做 自 增 管理 。 字 段 长 度 可 以 通过 


[client 
default-character-set=utf8 
[mysql 
default-character-set=utf8 
[mysqld 
character-set-server=utf8 

basedir=D: /taquarius/mysql-5.6.11-winx64 
datadir=D: /taquarius/mysql-5.6.11-winx64/data 
#10g 


log-error=D: /taquarius/mysql-5.6.11-winx64/logs/error.1log 


该 配置 是 MySQL 的 简约 配置 ， 分 别 定义 了 MySQL 客 户 端 和 服务 端的 字符 集 ， 服 务 器 端 MySQL 路 径 、 


2.5.4 ”集成 Query 


由 于 REST 式 的 Web 服 务 的 客户 端 只 需要 关注 HTTP 请 求 和 响应 的 展示 ， 


库 jQuery 来 实现 Browser/Server 模 式 的 客户 端 。 


jQuery 的 优点 是 普及 度 高 、 易 于 上 手 ,项 目 和 社区 非常 活跃， 文档 和 第 三 方 支持 


关于 jQuery 的 文档 和 书籍 很 多 ， 这 里 简 述 3 个 知识 点 。 第 一 个 知识 点 是 jQuery 的 引入 方式 ,我们 选择 了 WebJar， 原 因 
jQuery 完成 REST 请 求 的 基础 ; 第 三 个 知识 点 是 jQuery 的 选择 器 的 基本 使 用 。 


小 白 讲堂 


jQuery 是 一 个 活跃 的 JavaScript 库 项 


1. 使 用 WebJar 引 入 脚本 库 


在 Web 项 目 中 ， 使 F 
版 本 的 CDN 地 址 ， 然 后 在 依赖 该 库 的 脚本 文件 中 引 


下 面 是 这 两 种 方式 的 对 比 : 


:下载 的 好 处 是 加 载 速度 快 ， 缺 点 是 版 本 升级 和 管理 不 方便 ， 源 程序 总 体 较 大 。 


: CDN 的 好 处 是 源 代码 规模 较 小 ， 但 运行 时 加 载 时 间 较 长 。 


那么 有 没有 一 种 技术 可 以 综合 这 两 种 方式 的 优点 ， 却 没有 其 缺点 呢 ? WebJjar 就 是 基 


MySQL 数 据 路 径 和 错误 日 志 


F 这 种 思考 产 和 


E 的 。WebjJar 是 一 种 利 


后 面 会 讲 ; jQuery 的 第 二 个 知识 点 是 AJAX 请 求 的 AP1， 因 为 AJAX 是 我 们 使 


因此 与 服务 器 端 天 然 解 厢 ， 开 发 的 方法 很 多 ， 可 以 根据 具体 需求 , 利 


开源 的 工具 进行 快速 开发 。 本 节 使 


纯 HTML+JavaScript 


良好 。jQuery 的 开发 和 执行 的 效率 都 比较 理想 ， 对 于 


地 定义 Jar 包 的 版 本 号 ， 轻 松 地 管理 项 目 对 Javascript 库 的 依赖 。Jar 包 只 在 编译 期 下 载 ， 源 程序 中 只 有 声明 并 不 包含 Jar 包 ， 


出 ，WebJar 


此 ， 本 示例 将 引入 jQuery 的 WebJjar 来 实现 客户 端 页 面 的 功能 。 


2.AJAX 的 基本 使 用 


(1) $ 和 jQuery 符号 


符号 $ 是 jQuery 的 标准 命名 空间 的 缩 略 符号 ， 


虽然 AJAX 的 概念 已 经 广为人知 ， 但 是 jQuery 的 官方 文档 还 是 对 AJAX 函 数 进行 了 详细 介绍 ， 


来 代表 jQuery 对 象 。 但 是 ， 如 果 项 


中 同时 使 


了 其 他 脚本 库 ， 就 要 


面 对 一 个 问题 : 如 果 每 个 脚本 库 都 是 


如 何 区 分 呢 ? jQuery 框架 提供 了 在 与 其 他 JavasScript 库 共存 


jQuery.noConflict () 


(2) jQuery 的 AJAX 请 求 处 理 


jQuery 在 处 理 异 步 请 求 时 ,使 


“jQuery 1.0 引 入 的 jQuery.ajax ([settings]) 。 


4 被 其 他 JavaScript 库 使 


时 避免 冲突 


的 声明 。 这 一 声明 本 可 


jQuery.ajax() 方 法 。 该 方法 在 jQuery 发 展 过程 中 形成 了 两 种 不 同 参数 的 重 载 方法 : 


以 使 有 


任何 字符 ， 但 约定 俗 成 地 使 


晶 构 和 需求 的 增 量 改进 的 响应 比较 迅速 。 


， 升 级 较为 频繁 。 其 版 本 信息 可 以 通过 http://zh.wikipedia.org/zh-cn/JQuery 来 获得 。jQuery 的 下 载 地 址 为 http://jquery.com/download。 


第 三 方 的 Javascript 库 的 传统 方式 有 两 种 。 一 种 是 到 其 官网 上 下 载 合适 的 版 本 ， 然 后 将 其 放 入 项 目的 文件 目录 中 ， 比 如 webappNlibNjavascript 目 录 下 ; 另 一 种 是 找到 该 依赖 库 合 适 
该 CDN 地 址 。 


Maven 来 管理 和 封装 JavaScript 库 的 Jar 包 文件 ， 通 过 在 pom.xml 文 件 中 显 式 
因此 源 代码 体积 较 小 、 从 SCM 中 迁 出 速度 快 ， 且 版 本 切换 方便 。 可 以 看 
目前 ,已 经 有 很 多 脚本 库 支持 WebjJar 这 种 技术 ( 详 见 http://www.webjars.org/) ， 其 中 就 包括 jQuery。 因 


读者 可 以 通过 http://apijquery.com/jQuery.ajax 获 取 。 这 里 为 了 方便 读者 学 习 本 例 ， 只 介绍 相关 的 主要 参 


$ 符 号 来 代表 其 内 部 对 象 ， 浏 览 器 和 开发 者 该 


jQuery 这 个 名 字 。 定 义 如 下 : 


“ jQuery 1.5 引 入 的 jQuery.ajax (url[，settings]) 。 


本 节 使 用 Query 1.5 引 入 的 AJAX 方 法 版 本 。 


jQuery 1.5 定 义 的 jQuery.ajax0 方 法 主要 参数 简 述 如 下 。 
“ uf 参数 是 请 求 地 址 ，settings 是 可 选 的 键 值 对 参数 集合 。 
:async 参 数 是 发 送 异步 请 求 ， 黑 认 是 true， 当 不 显 式 声明 该 键 时 ， 均 发 送 异 步 请 求 。 当 设置 为 tlse 时 ， 执 行 同步 请 求 。 当 请 求 为 跨 域 或 者 dataType 设 置 为 jsonp 时 ， 同 步 请 求 无 效 。 


“ contentType 参 数 是 请 求 内 容 的 类 型 ， 对 应 HTTP HEAD 中 的 Content-Type， 默 认 值 为 'application/x-www-form-utlencoded;charset=UTF-8'，REST 应 用 中 更 为 常见 的 Content-Type 的 设置 


是 "application/json" 和 "application/xml"， 分 别 代表 JSON 和 XML 类 型 。 
“ data 参 数 是 请 求 数据 。 
“ dataType 参 数 是 服务 器 返回 数据 的 类 型 ， 可 以 是 xml、json、script、html、jsonp 和 text 类 型 。 
“ type 参 数 是 请 求 方法 类 型 ， 默 认 是 GET。 本 节 示 例 还 用 到 了 POST、PUT 和 DELETE。 


(3) jQuery 的 AJAX 响 应 处 理 


在 请 求 的 响应 阶段 ， 如 果 请 求 成 功 ， 那 么 Query.ajax() 使 用 回调 函数 “jqXHR.done (function (data，textStatus，jqXHR) 1f) ;” 来 处 理 响 应 返回 值 和 泻 染 页 面 。jqXHR 是 jQuery 的 XMLHTTP- 
Request 对 象 。 同 时 ，jqXHR.done() 方 法 可 以 代 蔡 过 时 的 jQuery 方法 qXHR.success(。 如 果 请 求 失败 ，jQuery.ajax() 使 用 回调 函数 “jqXHR.fail (function (jqXHR，textStatus，errorThrown) 1f) ”来 
处 理 异常 和 故障 并 演 染 页 面 。 同 时 ，jqXHR.fail( 方 法 可 以 代 蔡 过 时 的 方法 jqXHR.error()。 


3.Selector 的 基本 使 用 


jQuery 的 一 个 显著 的 特点 是 提供 了 强大 的 选择 器 (Selector) 。 通 过 $0 或 者 jQuery0 可 以 获取 指定 的 页 面 元 素 。 下 面 示 例 展 示 了 使 用 选择 器 读 取 pathUrl 元 素 的 值 和 写 入 resultDiv 元 素 。 


var url = $ 

("#pathUrl" 

) .val(); 

jQuery 

('#resultDiv' 

) .html 

(errorThrown + " status=" + textStatus.status 


到 此 ， 相 信 读 者 已 经 掌握 了 本 例 的 关键 技术 点 ， 如 果 再 结合 本 节 的 源 代码 进一步 操练 ， 一 定 会 完成 快速 入 门 JAX-RS 2.0 的 任务 。 按 照 前 面 对 REST 服 务 的 部 署 的 讲述 ， 部 署 并 启动 本 示例 ， 读 者 将 看 到 如 
到 2-8 所 示 的 首页 。 


Firefox ~ 


名 | @ localhost8080/simple-service-webapp-spring-jpa-jquery/ 


则 试 结果 

1 查询 全 部 (没有 分 页 功能 ) 
2 主键 查询 (query) 
/book?id=1 

3 主键 查询 (path) 


和 
4 更 新 


book Id: book name: publisher 


dataformat 图 json © xml 


5 出 除 
[EC 
6 新 增 


book name: publisher 


dataformat 图 json © xml 


图 2-8 第 一 个 完整 的 REST 服 务 首页 


在 图 2-8 中 ， 页 面 提供 了 图 书 资源 的 基本 的 增加 、 删 除 、 修 改 、 查 询 功能 。 填 充 输 入 框 并 单 击 相应 按钮 ， 流 程 将 进入 jQuery 实现 的 客户 端 请 求 ， 每 个 请 求 都 指向 本 示例 服务 器 端 提 供 的 一 个 REST 资 源 地 


在 本 章 即将 结束 时 ， 通 过 我 们 刚刚 完成 的 这 个 完整 的 示例 ， 来 一 起 学 习 一 下 Jersey 2.x 对 REST 请 求 处 理 的 流程 分 析 。 


2.5.5 ”请 求 处 理 流程 分 析 


在 进入 Jersey 2.x 请 求 处 理 流程 分 析 之 前 ,我 们 首先 要 清楚 流程 的 上 下 文 。 这 个 流程 是 存在 于 Servlet 容 器 中 的 ，Servlet 的 核心 处 理 依赖 于 Jersey 的 Server 模 块 。 首 先 从 宏观 上 要 和 弄 清楚 REST 服 务 开发 中 
的 依赖 关系 。 本 例 的 依赖 关系 如 图 2-9 所 示 。 
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1.0-SNAPSHOT 


jersey-container-servlel 
2.2 


jersey-container-servlet-core Jersey-server 
22 2.2 
jersey-common ff | | jersey-commol 
2:2 | \ py) 
| , 


| ' ) . . 
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2.0 


| \ 22 2.0 


章 
validation-apil |hk2-locator guava 
1.1.0.Fina 2.2.0-b14 14.0.1 | | 2.2.0-b14 


2-9 Jersey 包 依赖 关系 图 
2-9 中 ，REST 服 务 依赖 于 jersey-container-servlet， 该 包 依赖 于 Server 模 块 jersey-server。Server 模 块 依赖 于 Jersey 的 common 和 client 两 个 模块 ， 以 及 如 下 模块 : javax.ws.rs-api 是 JAX-RS 2.0 标 
于 容器 内 实现 DI 依赖 注入 的 架构 包 。guava 是 Google 对 JDK 功 能 扩展 和 增强 包 (在 
形 依赖 关系 树 ， 图 2-9 使 用 IDE 工 具 NetBeans 生 


Jersey-server 
2.2 


在 图 
准 包 ，validation-api 是 Bean 验 证 标准 (JSR-303) 包 ，javax.inject 是 依赖 注入 (D1) 标准 (JSR-330) 包 , hk2 是 


Jersey 2.6 版 本 后 不 再 依赖 此 模块 ) 。 更 多 的 依赖 关系 可 以 从 REST 服 务 的 根 目录 执行 Maven 命 令 “mvn dependency:tree” 获 得 ， 也 可 以 从 IDE 中 得 到 图 


成 。 在 了 解 了 模块 的 依赖 后 ， 我 们 开始 一 个 REST 请 求 流程 的 剖析 过 程 。 
一 个 REST 请 求 ， 开 始 于 客户 端 (/ 浏 览 器 ) 向 REST 服 务 器 发 起 的 请 求 ( 有 效 的 请 求 必须 包含 一 个 有 效 的 RESTful Web Service 资 源 的 地 址 ) ， 结 束 于 服务 器 返回 一 个 客户 端 可 接收 的 资源 表述 (比如 


JSON) 。 因 此 ， 流 程 分 析 的 关键 切入 点 有 两 个 : 


: 将 请 求 地 址 映射 到 资源 类 的 相应 方法 上 ， 并 执行 该 方法 。 


“ 将 返回 值 转换 成 请 求 所 需要 的 表述 ， 并 返回 给 客户 端 。 


对 于 第 一 个 切入 点 ， 是 请 求 阶段 的 核心 过 程 ， 我 们 可 以 将 其 分 解 为 如 下 3 个 步 又。 
“URI 到 服务 入 口 : 从 客户 端 向 服务 器 的 URI 发 起 请 求 到 服务 器 端 接 收 该 请 求 。 
“URI 资源 定位 和 方法 匹配 : 服务 器 端 处 理 该 请 求 并 匹配 相应 的 资源 方法 。 


“ 资源 方法 调用 : 调用 匹配 到 的 资源 方法 。 


对 于 第 二 个 切入 点 ， 处 于 请 求 处 理 的 响应 阶段 ， 我 们 可 以 将 其 分 解 为 如 下 两 个 步骤 。 
“ 准备 响应 实例 : 从 资源 方法 结束 到 Response 实 例 准备 完毕 。 


“ 处 理 表述 : 特定 表述 的 拦截 器 实现 类 处 理 资源 方法 返回 值 ， 并 最 终 返 回响 应 到 客户 端 。 
cURL 发 起 REST 请 求 ， 资 源 地 址 是 : http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1， 客 户 端 期 待 的 表述 


理 清 了 思路 后 ， 我 们 开始 动手 操作 。 本 节 使 
媒体 类 型 是 JSJON ， 匹 配 的 资源 方法 是 com.example.resource.BookResource.getBook-ByQuery (Integer) 。 请 求 命令 如 下 : 


curl -H " Accept:application/json" 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1 


-H 参 数 定义 了 HTTP 头 信息 指定 Accept 类 型 ， 期 待 的 响应 实体 类 型 是 JSON: Accept:application/json。 


该 脚本 发 送 了 一 个 HTTP GET 请 求 , 使 
下 面 我 们 进入 第 一 个 切入 点 ， 分 别 讲解 3 个 步骤 的 流程 ， 从 中 可 以 掌握 Jersey 是 如 何 将 请 求 地 址 匹配 到 资源 类 的 相应 方法 上 ， 并 触发 该 方法 的 。 


1. 从 请 求 到 资源 方法 
首先 ， 我 们 在 第 一 步 先 来 看 从 请 求 一 个 URL 到 进入 资源 方法 的 流程 。 


(1) service 入 口 方 法 


CURL 客 户 端 发 起 请 求 后 ， 服 务 器 由 Servlet Container 类 实例 来 接收 请 求 并 将 处 理 分 派 下 去 。ServletContainer 类 的 继承 关系 树 ， 如 


到 2-10 所 示 。 


目 Package Pe Type Hie 3 Jo JUnit 


ServletContainer - org.glassfish,jersey.servlet 


4 ID ServletContainer 
4 O° HttpServlet 
4 BO GenericServlet 
加 Object 
人 @ Serializable 
Senlet 
人 ServletConfig 
4 Container 
《9 Filter 


2-10 ServletContainer 继 承 关系 


从 图 2-10 可 知 ，ServletContainer 是 HttpServlet 的 子 类 ， 位 于 Jersey 的 Servlet 容 器 包 中 (jersey-container-servlet-core-2.xjar) ， 作 为 Servlet 接 口 的 实现 类 同时 实现 了 JAX-RS 2.0 的 过 滤器 接口 
Filter 和 容器 接口 Container。 我 们 知道 ，Servlet 接 口 的 service 方 法 是 Web 工 程 中 请 求 的 入 口 方法 ， 任 何 HTTP 方 法 的 请 求 都 要 先 经 过 HttpServlet 类 及 其 子 类 的 service 方 法 。 因 此 ， 我 们 首先 关注 
ServletContainer.service 方 法 栈 变 量 ， 示 例如 下 。 


ServletContainer.servVice 

(HttpServletRequest, HttpServletResponse 

) line: 248 

baseUri 

http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/ 

requestUri 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1 


断 点 栈 是 当前 线程 的 快照 ， 我 们 从 中 关注 两 个 重要 的 变量 : 请 求 地 址 信息 的 baseUri 和 requestUri， 这 两 个 变量 将 作为 后 续 流程 的 输入 。baseUri 的 值 为 http://localhost:8080/simple-service- 
webapp-spring-jpa-jquery/webapi/， 这 是 REST 服 务 的 基本 路 径 。requestUri http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1， 这 是 请 求 服务 的 资源 路 
径 。 


从 容器 层级 上 看 ， 请 求 上 下 文 变量 除了 包括 请 求 地 址 信息 外 ， 还 包括 请 求 头 信息 。 这 里 我 们 关注 请 求 头 中 的 accept 字 段 信 息 ， 该 字段 对 流程 分 析 至 关 重 要 。 


ServletContainer. service 
(URI, URI, HttpServletRequest, HttpServletResponse 
) line: 372 
requestContext .header {user-agent=[curl/7.26.0], host=[localhost:8080], 
accept=[application/json]} 


在 断 点 栈 中 ，ServletContainer.service 方 法 处 理 请 求 上 下 文 的 header 信 息 ， 可 以 看 到 accept 的 值 为 [application/json]， 代 表 接收 JSON 类 型 的 数据 。 


如 果断 点 位 于 service 方 法 ， 可 以 从 断 点 继续 单 步 执行 ， 如 果断 点 直接 设 在 资源 方法 ， 可 以 观察 栈 调用 信息 ， 流 程 是 按照 ServletContainer 一 WebComponent 一 ApplicationHandler 一 ServerRuntime 
的 顺序 来 处 理 Container Request 的 ， 参 见 图 2-11。 到 此 ，URI 到 服务 入 口 的 分 析 就 结束 了 。 
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图 2-11 Jersey 请 求 处 理 时序 图 


回 


如 图 2-11 所 示 ， 在 ServerRuntime 类 的 process 方 法 中 ， 创 建 了 一 个 线程 任务 ， 该 任务 在 静态 类 Errors 中 被 


调 执行 ，Errors 会 处 理 该 任务 出 现 的 异常 。 因 此 ， 流 程 的 重点 就 在 这 个 线程 任务 中 。 


(2) 匹配 对 应 方法 


接 下 来 我 们 进入 第 二 个 步骤 (URI 资源 定位 和 方法 匹配 ) 的 分 析 。 刚 刚 创建 的 处 理 线程 首先 会 调用 静态 类 Stages 从 请 求 处 理 Stage 链 的 根部 一 端 走 一 遍 到 链 的 端 部 ， 逐 个 stage 调用 其 apply 方 法 。 示 例 
代码 如 下 。 


final Stage<ContainerRequest> rootStage = Stages 
.Chain (locator.createAndIinitialize (ReferencesInitializer.class) ) 
.to(locator.createAndIinitialize (ContainerMessageBodyWorkersInitializer.class)) 
.to (PreMatchRequestFilteringStage) 
.to (routingStage) 
.to (resourceFilteringStage) 
.build(routedInflectorExtractorStage); 


本 例 是 最 简单 的 流程 ， 因 此 没有 其 他 Stage 做 apply 操 作 。 当 在 Stages 类 中 找到 这 个 端点 后 ， 会 将 其 放 入 inflectorRef 中 ， 流 程 回 到 处 理 线程 。 示 例 代码 如 下 。 


ServerRuntime$1.run() line: 237 
final Ref<Endpoint> endpointRef = Refs.emptyRef (); 
final ContainerRequest data = Stages.process (request, requestProcessingRoot, endpointRef); 
final Endpoint endpoint = endpointRef .get (); 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
asyncContextFactoryProvider.get () .set (asyncResponderHolder); 
final ContainerResponse response = endpoint.apply (data); 
Stage.Continuation<DATA> continuation = Stage.Continuation.of (data, lastStage); 
while (continuation.next() != null) { 
lastStage = continuation.next (); 
continuation = lastStage.apply (continuation.result ()); 


} 
inflectorRef .set (Stages.<DATA, RESULT, T>extractIinflector (lastStage)); 


线程 流程 走 到 endpointRef.get( 时 返回 端点 实例 ， 这 个 端点 就 是 ResourceMethodlnvoker 实 例 。 调 用 该 实例 的 apply 方 法 ， 流 程 就 进入 请 求 地 址 匹配 的 方法 了 。 因 此 ， 第 2 步 流 程 到 这 里 完毕 


(3) 调用 匹配 方法 


接 下 来 是 第 三 步 (URI 资 源 定位 和 方法 匹配 ) 的 分 析 。ResourceMethodlnvoker 实 例会 调用 匹配 好 的 REST 请 求 处 理 方法 。 示 例 代 码 如 下 。 


ResourceMethodInvoker .invoke (ContainerRequest, Object) line: 353 

dispatcher.dispatch (resource, requestContext); 

JavaResourceMethodDispatcherProvider$TypeOutInvoker ( 

AbstractJavaResourceMethodDispatcher) .invoke (Object, Objecthttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/O0EBPS/Text/...) line: 15 
invokeMethodAction.run(); 

ResourceMethodInvocationHandlerFactory$1 .invoke (Object, Method, Object[]) line: 81 

BookResource.getBookByQuery (Long) line: 71 


从 断 点 栈 中 可 以 看 到 ， 最 终 调用 的 REST 请 求 处 理 方法 就 是 我 们 期 待 的 getBookByQuery() 方 法 ， 此 后 的 ResourceMethodlnvocationHandlerFactory 的 invoke() 方 法 将 调用 这 个 方法 处 理 对 应 的 REST 请 


求 。 


到 此 ， 请 求 地 址 到 资源 方法 调用 的 流程 就 结束 了 。 在 处 理 业务 逻辑 方法 BookResource.getBookByQuery0 后 ，Jersey 将 开始 处 理 响应 信息 。 


2. 响 应 和 表述 的 处 理 


响应 流程 开始 于 资源 方法 执行 结束 。 在 资源 方法 完成 业务 逻辑 处 理 后， 也 将 结束 JDK 动 态 代理 的 invoke() 方 法 。 因 此 ， 观 测 点 可 以 选择 在 InvocationHandler 接 口 的 invoke( 方 法 中 。 示 例 代 码 如 下 。 


@Singleton 
public final class ResourceMethodInvocationHandlerFactory 
implements ResourceMethodInvocationHandlerProvider { 
private static final InvocationHandler DEFAULT HANDLER = new InvocationHandler() { 
QOverride 可 
public Object invoke 
(Object target, Method method, Object[] args 


throws IllegalAccessException, 
IllegalArgumentException, InvocationTargetException { 
dd 


六 反射 调用 资源 方法 


return method. invoke 
(target, args 
} 
六 


(1) 准备 响应 实例 


在 invoke() 方 法 中 ，target 是 资源 类 实例 ，method 是 资源 方法 ，args 是 该 方法 的 输入 参数 。method.invoke (target，args) 一 行 通过 反射 机 制 执行 该 方法 ， 见 关注 点 1。 


流程 会 返回 方法 method.invoke(0 执 行 结果 对 象 作为 invoke() 方 法 的 返回 值 ， 然 后 在 JavaResourceMethodDispatcherProvider 类 实例 的 分 派 方法 doDispatch(0 中 ， 将 这 个 返回 对 象 置 入 response 的 实 


体 中 。 示 例 代码 如 下 。 


JavaResourceMethodDispatcherProvider$TypeOutInvoker.doDispatch 
(Object, Request 

) line: 198 

© Book 

(id=2686 

) 


Response response = Response.ok() .entity 


o 
) .build(); 


在 断 点 栈 中 ， 类 型 为 图 书 实体 类 Book 的 实例 o 是 invoke() 方 法 的 返回 值 ， 该 对 象 作 为 响应 的 实体 传 入 HTTP 状 态 为 ok 的 Response 实 例 中 。 


REST 请 求 的 响应 信息 至 少 包 括 响应 实体 ( 某 种 媒体 格式 的 表述 信息 ) 和 响应 头 信息 (包括 HTTP 响 应 代码 ， 通 常 一 个 成 功 的 请 求 应 该 得 到 200 OK) 。 这 就 是 上 述 断 点 栈 最 后 一 行 代码 所 做 的 事情 。 在 设 
置 好 response 的 entity 后 ， 需 要 将 该 entity 对 象 转化 成 请 求 所 接受 的 表述 返回 给 客户 端 /浏览 器 。 但 在 此 之 前 ， 需 要 将 ContainerResponse 响 应 对 象 返回 给 ServerRuntime。 


接 下 来 serverRuntime 将 使 用 processResponse() 方 法 处 理 响应 实例 ， 示 例 代码 如 下 。 


private ContainerResponse processResponse 
(ContainerResponse response 


) 


了 
(respondingRoot != null 
站 


response = Stages.process 
(response, respondingRoot 


writeResponse 
(response 


{ 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
if 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


processResponse() 方 法 主要 做 两 件 事情 : 第 一 ， 逐 个 Stage 执 行 apply， 和 前 面 request 流 程 类 似 。 第 二 ， 执 行 资源 的 后 置 过 滤器 和 拦截 器 ， 拦 截 器 会 将 返回 值 写 向 通 向 客户 端 /浏览 器 的 通道 。 


可 
立 
图 
回 


ServerRuntime$Responder .process (ContainerResponse) line: 351 
ServerRuntime$Responder .writeResponse (ContainerResponse) line: 486 
entity Book (id=7076) 

executor WriterIinterceptorExecutor (id=7125) 


值 的 流程 起 始 于 serverRuntime 的 process() 处 理 方法 ， 该 方法 会 将 资源 方法 的 返回 对 象 实体 写 入 连接 客户 端的 通道 


从 栈 中 可 以 看 到 ， 这 个 阶段 重点 的 两 个 对 象 是 返回 对 象 和 写 处 理 对 象 ， 流 程 要 做 的 就 是 使 


后 者 将 前 者 恰当 地 写 入 返回 客户 端的 通道 中 ， 这 个 “恰当 ”的 工作 就 包括 了 对 表述 格式 的 处 理 。 接 下 来 ,我 


们 进入 表述 处 理 流程 。 


(2) JSON 表 述 


本 例 中 我 们 定义 的 accept 媒 体格 式 是 JSON。REST 的 表述 不 局 限于 JSON， 这 里 我 们 以 JSON 作 为 常用 的 表述 类 型 为 例 ， 来 和 


究 Jersey 的 表述 处 理 。 


Jersey 对 JSON 的 支持 有 4 种 方式 ， 在 3.3 节 会 有 详细 的 讲述 。 本 例 使 用 的 是 默认 的 方式 ， 即 使 用 EclipseLink 项 目的 MOXy 包 来 处 理 JSON 数 据 ，MOXy 包 同时 也 是 JPA 的 底层 依赖 〈 另 一 个 著名 的 JPA 实 现 


是 JBoss 项 目 集 下 大 名 昂昂 的 Hibernate) 。MOXy 包 依赖 定义 示例 如 下 。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-moxy</artifactId> 
<version>$ {jersey.version}</version> 
</dependency> 


继续 刚才 说 到 的 响应 流程 的 写 入 阶段 ， 此 时 要 做 的 事情 就 是 将 返回 对 象 转 换 为 JJON 格 式 的 响应 实体 。 这 正 是 MOXy 要 做 的 工作 ， 如 下 是 流程 进入 MOXy 的 代码 栈 信息 。 


JsonWithPaddingInterceptor.aroundWriteTo (WriterInterceptorContext) line: 91 
WriterInterceptorExecutor$TerminalWriterIinterceptor.aroundWriteTo( 
WriterInterceptorContext) line: 188 

ConfigurableMoxyJsonProvider (MOXyJsonProvider) .writeTo (Object, Class<?>, Type, 
Annotation[], MediaType, MultivaluedMap<String,Object>, OutputSstream) line: 782 
object Book (idq=7076) 

type Class (com.example.domain.Book) (id=568) 

genericType Class (com.example.domain.Book) (id=568) 

annotations Annotation[3] (id=7098) 

mediaType AcceptableMediaType (id=7120) 

httpHeaders StringKeyIgnoreCaseMultivaluedMap (id=7121) 

entityStream CommittingOutputSstream (id=7124) 


在 这 段 栈 信 息 中 ，JsonWithPaddinglnterceptor 是 拦截 器 实现 类 ，aroundWriteTo() 方 法 实现 了 JSON 格 式 数据 的 写 入 。 再 往 下 跟踪 ， 可 以 看 到 JAXB 的 “身影 ”， 因 为 MOXy 同 样 实 现 了 JAXB 标 准 ， 流 
程 中 处 理 Java 对 象 为 /SON 数 据 的 内 部 实现 原理 是 以 XML 的 Marshal 方 式 处 理 Java 对 象 成 XML 格 式 的 数据 (OXM:Object-XML-Mapping) ， 然 后 再 将 XML 转化 为 JSJON 数 据 (XML-2-JSON) ， 详 见 4.2 


节 。 接 下 来 的 流程 是 将 对 象 转化 为 JJON 数 据 ， 这 是 一 个 marshal 的 过 程 。 


接着 流程 会 返回 到 处 理 线程 ， 执 行 到 如 下 一 行 。 最 后 是 将 response 返 回 并 释放 资源 。 


ServerRuntime$Responder .processResponse 
(ContainerResponse 
) line: 362 


流程 分 析 到 此 结束 。 希 望 读 者 可 以 通过 这 一 次 REST 请 求 的 分 析 之 旅 对 Jersey 的 REST 请 求 处 理 流程 中 的 各 个 步骤 有 个 总 体 印象 ， 这 对 以 后 更 好 地 编写 REST 服 务 代码 会 有 帮助 。 也 借 此 让 初学 者 了 解 如 何 


利用 断 点 来 调试 和 分 析 流 程 。 


2.6 REST 调 试 工具 


在 上 节 中 ， 我 们 不 但 知道 了 REST 请 求 处 理 流程 ， 而 且 对 IDE 中 设置 断 点 、 观 察 服务 器 端 运 行 时 变量 有 了 了 解 。 本 节 将 讲述 如 何在 客户 端 对 REST 服 务 进行 调试 。 


为 何 需要 在 客户 端 调试 REST 服 务 呢 ?因为 在 REST 开 发 过 程 中 ， 需 要 对 请 求 资源 地 址 、 资 源 所 支持 的 数据 媒体 类 型 和 返回 值 类 型 等 进行 调试 和 测试 。 因 此 ， 掌 握 客 户 端的 调试 工具 是 开发 优秀 的 REST 服 
务 的 前 提 。 接 下 来 ， 将 介绍 这 一 领域 常用 的 REST 请 求 工具 ， 以 使 读者 更 进一步 地 熟悉 REST 开 发 和 调试 。 


2.6.1 命令 行 调 试 工具 cURL 


cURL 是 非常 易 用 、 强 大 的 基于 URL 标 准 (RFC 3986) 的 命令 行 工具 ， 通 过 命令 行 即 可 完成 多 种 协议 (比如 HTTP) 的 请 求 ， 并 可 以 将 请 求 的 响应 信息 输出 在 终端 /控制 台 上 ， 因 此 对 于 调试 和 测试 REST 
请 求 非常 方便 。 在 2.5.5 节 的 流程 分 析 中 ， 我 们 已 经 使 用 过 cRUL， 本 节 将 进一步 介绍 这 个 工具 的 使 用 。 


小 白 讲 堂 


下 面 是 “维基 百科 "对 cURL 的 解释 。 


cURL 是 一 个 利用 URL 语 法 在 命令 行 下 工作 的 文件 传输 工具 ，1997 年 首次 发 行 。 因 为 它 支持 文件 上 传 和 下 载 ， 所 以 是 综合 传输 工具 。 但 按照 传统 ， 习 惯 称 cURL 为 下 载 工具 。cURL 还 包含 了 用 于 程序 开发 
的 libcurl。 


cURL 支持 的 通信 协议 有 FTP、FTPS、HTTP、HTTPS、TFTP、SFTP、Gopher、SCP、Telnet、DICT、FILE、LDAP、LDAPS、IMAP、POP3、SMTP 和 RTSP。 


libcurl 支 持 的 平台 有 Solaris、NetBSD、FreeBSD、OpenBSD、Darwin、HP-UX、IRIX、AIX、Tru64、Linux、UnixWare、HURD、Windows、Symbian、Amiga、OS/2、BeOS、Mac OS X、Ultix、QNX、 
BlackBerry Tablet OS、OpenVMS、RISC OS、Novell NetWare、DOS 等 。 


(1) 最 简单 的 cURL 命令 


首先 利用 上 一 节 示 例 所 提供 的 REST 服 务 ， 通 过 一 个 REST 请 求 来 掌握 cURI 的 使 用 。 启 动 上 节 开 发 的 REST 服 务 ， 然 后 在 命令 行 中 输入 如 下 一 行 命令 。 


curl -H "Accept: application/json" 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1 


在 上 述 命令 中 ，cur 默 认 发 送 的 是 HTTP GET 请 求 方法 ，-H 参 数 中 定义 了 请 求 头 信息 ， 本 例 将 通知 服务 器 只 接收 application/json 类 型 的 表述 。 命 令 的 最 后 是 HTTP 请 求 的 地 址 信息 ， 这 个 资源 地 址 表示 
获取 图 书 1D 为 1 的 图 书信 息 。 在 执行 该 命令 后 ，REST 服 务 会 给 出 响应 ， 示 例如 下 。 


{"bookId":1, "bookName":"Java Restful Web Service 
使 用 指南 "， "publisher":"cmpbook"} 


从 结果 可 以 看 出 ， 这 是 个 JSON 格 式 的 数据 ， 键 值 对 描述 了 ID 为 1 的 
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(2) 获取 区 间 信息 的 命令 


第 一 个 cURL 示例 请 求 的 地 址 是 一 个 唯一 确定 的 


出 


书 资源 信息 ， 接 下 来 的 例子 中 的 地 址 信息 是 一 个 区 间 ， 而 不 是 唯一 地 址 。 


curl http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/{1,2} 


从 cURL 命令 的 地 址 中 可 以 看 到 ， 我 们 要 获取 的 是 一 个 区 间 信息 ，{1，2} 代 表 图 书 的 ID 是 1 和 2。 因 为 我 们 没有 在 cURL 命令 中 使 用 -H 来 定义 请 求 头 信息 ， 因 此 返回 实体 默认 的 媒体 格式 是 XML 格 式 的 表 
服务 器 的 响应 信息 如 下 所 示 。 


[1/2]: http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/1 --><stdout> 

--_curl --http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/1 

<?xml Version="1.0" encoding="UTF-8" standalone="yes"?><book bookId="1" bookName="Java Restful Web Service 
使 用 指南 " publisher="cmpbook"/> 

[2/2]: http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/2 --><stdout> 

--_curl --http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/2 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book bookId="2" bookName="JSF2 

和 RichFaces4 

使 用 指南 "publisher="phei"/> 


从 上 述 结果 可 以 看 到 ， 返 回 的 结果 集 包 含 两 条 XML 格式 的 数据 ， 分 别 是 ID 为 1 和 2 的 
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在 cURL 的 帮助 手册 中 ， 对 使 用 一 组 URL 作 为 请 求 地址 的 示例 如 下 所 示 。 


http://site. {one, two, three} .com 
ftp://ftp.numericals.com/file[1-100] .txt 
ftp://ftp.numericals.com/file[001-100] .txt 

(with leading zeros 
)》 
ftp://ftp.letters.com/file[a-z] .txt 
http://www.numericals.com/file[1-100:10] .txt 
http://www.letters.com/file[a-z:2] .txt 
http://any.org/archive[1996-1999] /vol [1-4] /part{a,b,c}.html 


cURL 的 请 求 不 仅 局 限于 HTTP 请 求 ， 还 包括 FTP 等 协议 。 资 源 路 径 可 以 包含 区 间 信息 ， 小 括号 是 开 区 间 ， 中 括号 是 闭 区间 ， 大 括号 是 指定 数值 的 集合 。 


(3) 请 求 写 操 作 的 命令 


cURL 默认 的 请 求 方法 是 GET， 但 不 局 限于 只 读 请 求 。 我 们 还 可 以 使 用 cURL 提交 XML 数 据 到 服务 器 ， 完 成 写 操作 ， 示 例如 下 。 


Curl -~v -X POST -H "Content-Type:application/xml" -H "Accept: application/xml" 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books --data-binary 
"<book bookName="'JAX-RS2'/>" 

Curl -~v -X PUT -H "Content-Type:application/xml" -H "Accept: application/xml" 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/2 -d 

"<book bookName="'JAX-RS2' publisher='CMP'/>" 


CURL 命 令 的 参数 -X 用 于 显 式 声明 HTTP 请 求 方法 ， 示 例 中 分 别 使 
的 是 双 引 号 ， 其 内 部 使 用 的 是 单 引号 。 


同样 ， 对 于 提交 JSON 数 据 到 服务 器 的 示例 如 下 。 


了 POST 和 PUT， 参 数 --data-binary (或 者 使 


缩写 形式 -d) 定义 提交 的 数据 内 容 。 这 里 需要 注意 的 是 ，XML 格 式 的 数据 ， 其 外 部 使 


Curl -~v -X PUT -H "Content-Type:application/json™" 
http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/3 -d 
"{\"bookName\":\"JAX-RS2\", \"publisher\":\"CMP\"}" 


JSON 数 据 只 使 


双 引 号 ， 内 部 没有 使 


在 提交 写 请 求 后 ， 可 以 使 


基本 的 cURL 请 求 对 其 进行 验证 ， 示 例如 下 。 


单 引号 。 如 果 JSON 内 部 使 用 单 引 号 ， 服 务 器 会 对 单独 字符 进行 解析 ， 


转 义 字符 和 双 引 号 的 组 合 来 表示 JSON 数 据 内 部 的 双 引 号 。 


curl http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/3 


最 后 要 注意 的 地 方 是 ， 如 果 REST 请 求 的 服务 器 需要 走 代理 ， 在 cURL 的 请 求 命令 中 应 使 


因为 上 述 的 PUT 请 求 定义 了 图 书 ID 等 于 3， 并 更 新 了 该 图 书信 息 ， 所 以 验证 过 程 只 需 请 求 ID 为 3 的 图 书信 息 。 


参数 --proxy， 示 例如 下 。 


curl --proxy <[protocol://] [userepassword]Proxyhost [ :Port]> 


cURL 的 优点 是 简单 方便 ， 缺 点 是 没有 


出 


形 化 界 


2.6.2 ”基于 浏览 器 的 图 形 化 调试 插件 


。 下 面 将 介绍 几 款 基 于 浏览 器 的 扩展 插件 ， 作 为 REST 客 户 端 调试 工具 使 用 。 


cURL 功能 强大 ， 易 于 在 自动 化 脚本 中 使 


测试 REST 服 务 时 选择 使 用 。 


基于 Chrome 浏 览 器 的 REST 揪 件 有 很 多 ， 本 节 将 介绍 其 中 的 三 种 。 每 种 的 测试 均 使 


http://www.flickr.com/services/api/explore/flickr.people.getinfo 页 面 ， 获 取 用 户 在 Flickr 账 户 的 有 效 值 。 


(1) Simple REST Client 插 件 


Simple REST Client 插 件 是 基于 Chrome 浏 览 器 的 扩展 ， 安 装 该 插件 后 Chrome 窗 


的 右上 方 会 出 现 该 插件 的 图 标 ， 以 方便 


照片 存储 社交 网 站 Flickr 公 布 的 REST API。 对 Flickr 网 站 的 REST 请 求 需 


户 使 有 


， 但 cURL 的 每 个 请 求 都 要 通过 输入 文字 来 完成 ， 且 没有 图 形 界面 ， 并 不 适 于 所 有 读者 。 下 面 将 介绍 几 种 基于 浏览 器 的 图 形 化 调试 插件 ， 以 方便 读者 在 开发 和 


户 ID， 读 者 可 以 通过 访问 


。 该 项 目的 地 址 是 : https://github.com/jeremys/Simple-Rest- 


Client-Chrome-Extension， 插 件 的 下 载 地 址 是 : http://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpdjmb。Simple REST Client 插 件 的 界面 如 图 2-12 所 示 。 


(BB simple REST client 


Request 


URL: http://apiflickr.com/semces/rest/?method=flickr people.gstlnfo&apl_key=4dr05e3csf/106d6d75109e0fa0f9a0Suser_ id=56666695 © Bformat=rest 


Method: ®@ GET © POST ©PUT @DELETE ® HEAD @ OPTIONS © 


G) 


Headers: 


Status: 200 OK 


Date: Tue, 08 Oct 2013 13:40-34 GMT 

Via: HTTP/1.1 r35.ycpi tw1.yahoo.net UserFibarFramework/1.0 
Serer YTS/1 19 .11 

Ags:10 


Vary: Accept-Encoding 


Headers: 


P3P: policyref="http://into.yahoo.conm/w3c/lp3p-xml", CP="CADO DSP COR CUR ADM DEV TAI PSA PSD IVAi IVD CON TELo OTPI OUR DEL SAMI OTRi UNRI PUBIIND PHY ONL UNI PUR FIN COM NAV INT DEM 


CNT STA POL HEA PRE LOC GOV 
ContentEncoding: gzip 

Cache-Control prvate 

Connection: Keep-Alive 

Content-Type: text/xml; charset=uif-8 
Content-Length. 396 

X-Seved-By: www50 flickr.bfl .yahoo.com 


© 


0 encoding=" ut 


> 
66668058N0 ” 1conserver="6126" 


<location /> 
Ctinezone label-"Heijing, Chcengeaing, Hong Keng, Urungi™ offset="+08:00" /> 
Cdescription /> 
<photosurl>http:,/ www. flickr. com/'p} feuyeux/ /photos 
<profilenrl>http:// www. flickr. co pecple/feuyeuz/ /Drof 
<mobileurl>httn://n, flickr. con/ photostrean. ene?id-: bileur]l> 
<photos> 

<firstdatetaken>2011-08-27 1]:23:43¢/firstdatet axen> 

<firstdate71315153536</firstdate7 

<count >245C/coumt? 


Simple REST Client 插 件 的 特点 是 简单 易 用 ， 


1Lcorfarmr= "6”path_alisa="feu7eux > 


图 2-12 ”Simple REST Client 插 件 示 意图 


其 界面 分 为 请 求 信息 录入 和 响应 信息 展示 上 下 两 部 分 。 录 入 部 分 包括 URL、HTTP 请 求 方法 和 请 求 头 三 部 分 ， 见 图 2-12 中 上 方 的 数字 标识 1~3。 其 


中 ，HTTP 请 求 方法 支持 HTTP 的 标准 方法 GET、POST、PUT、DELETE、HEAD 和 OPTIONS，Headers 部 分 需要 完全 手工 输入 。 响 应 信息 部 分 包括 响应 状态 、 响 应 头 和 响应 实体 三 部 分 。 其 中 ，Headers 部 


分 展示 HTTP 请 求 交互 的 响应 头 信息 ，Data 中 


芒 泵 \ 


总 体 上 说 Simple REST Client 播 件 ， 虽 小 却 功能 比较 齐全 ， 但 相 比 后 面 要 讲 的 插件 仍 不 够 强大 。 


(2) Advance REST Client 插 件 


Advance REST Client 可 以 看 做 Simp 


的 是 响应 实体 信息 ， 语 法 高 亮 显示 ， 见 图 2-12 中 下 方 的 数字 标识 4~6。 


e REST Client 的 增强 版 。 该 项 目的 地 址 是 : https://code.google.com/p/chrome-rest-client， 揪 件 的 下 载 地 址 是 : 


https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo。Advance REST Client 插 件 界面 见 图 2-13 所 示 。 


Advance REST Client 提 供 更 为 丰富 的 功能 ， 除 了 Simple REST Client 插 件 具 备 的 输入 和 输出 ( 见 图 2-13 中 的 数字 标识 ) ，Advance REST Client 还 支持 带 参数 的 请 求 和 提交 表单 等 更 完整 的 请 求 功能 。 
数据 格式 上 ， 支 持原 生 的 格式 (Raw) 、XMI 格 式 的 响应 (Response) 信息 。Advance REST Client 支 持 对 请 求 地 址 的 保存 和 对 最 近 使 用 地 址 的 记忆 ， 如 果 调 试 中 需要 多 次 测试 同一 个 资源 地 址 ， 那 么 可 以 
将 其 保存 下 来 供 以 后 使 用 ;而 多 个 这 样 的 地 址 也 可 以 按照 项 目 分 别 保存 ， 方 便 区 分 使 用 。 


Advanced Rest [Unnamed] 


b http-//apiflickr.com/services/rest/?method=flickr. people.getinfoS&api_ key=4d705e3cef7 10606d75109e0fa0ff9a0Suser id=566666959 Sformat=rest 


@GET ©POST ©PUT 目 PATCH@DELETE ©HEAD © oPTONS © Other 
Raw Form Headers 
Projects 
Saved 
History 
Settings 


Aboui 


Status 200 OK WB Loadingtime: 1319 ms 出 


Request User-Agent Mozillals.0 (Windows NT 6.1; WOW64)APPISWeblMt537.361KHTML, like Gecko) Chromef29,.0,.1547.66 Safari537.36 
Donate headers Content-Type: textiplain; chars et=utf-g 
Accept :六 


application ¥ 


Accept-Encoding: czip, defiate, sdch 

Accept-Language: en-US,en:q=0.8 

Cookie: BX=4667da595819q0&b=3&s=InN; Xb=826871; BA=ba=08t=1381238915; current_identity=1-1291481854; cookie_session=56643641%3Ae549 
sa=1396423020%3A566656595%40N03%3Aa2cfrcf81458686c5d35bb1e07e84699; flrb=24: RT=3=1381239067219&u=&r=http%3Awwwflickr.comy: 
ftoto=0%2C0%2C0%2C0%2C1%2C0%3B0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%2C0%3B0%3B0%3Bf040d5067e9| 
hk%3Bus%3Bon 


Response Age: 0 
headers Cache-Control: private 

Connection: Keep-Alive 

Content-Encoding: gzip 

Content-Length: 396 

Content-Type: texthboml: charset=utf-6 

Date: Tue, 08 Oci 2013 13:49:10 GMT 

P3P: policyref="httpJ/info.yahoo.comiw3cp3p.xml” CP="CAD DSP COR CUR ADNM DEV TAI PSA PSD IVA IVDi CONiTELo OTPIi OUR DEL SAMi OTRi 

PRE LOC GOW 

Server: YTS/1.19.11 

Vary: AcceptEncoding 

Via HTTPI1.1 r24.7cpitw1.Yahoo.net UserFiberFramework/1.0 

X-Served-By www110. 布 ckr bf1yahoo.com 


Raw XML Response 


Copy to clipboard Save as file 


encoding= utf-—8 


图 2-13 ”Advance REST Client 插 件 示 意图 
(3) Postman-REST Client 插 件 


Postman-REST Client 是 基于 Simple REST Client 源 代码 编写 的 专门 针对 REST 的 插件 。 该 项 目的 地 址 是 : https://github.com/a85/POSTMan-Chrome-Extension， 揪 件 的 下 载 地 址 是 : 
http://www.getpostman.com。Postman-REST Client 揪 件 界面 如 图 2-14 所 示 。 


Postman-REST Client 提 供 的 功能 更 多 ， 除 了 Advance REST Client 具 有 的 输入 和 输出 ( 见 图 2-14 的 数字 标识 部 分 ) ， 还 可 以 发 起 基于 安全 的 请 求 。 请 求 方法 不 仅 包 括 HTTP 的 标准 方法 ， 还 包括 
WebDAV 标 准 的 方法 。 其 响应 信息 的 展示 和 支持 的 格式 也 更 丰富 。 如 果 读 者 希望 深入 和 细致 地 调试 REST 服 务 ，Postman-REST Client 要 比 其 他 插件 更 加 胜任 。 可 以 说 三 个 插件 的 复杂 度 和 功能 性 是 递增 的 ， 
使 用 哪 一 个 要 看 读者 的 需求 。 类 似 的 Chrome 插 件 很 多 ， 读 者 如 果 有 兴趣 ， 可 以 通过 https://chrome.google.com/webstore/category/extensions 这 个 链接 访问 Chrome 的 网 上 商店 ， 搜 索 更 多 的 Chrome 


插件 。 


(4) Firefox 播 件 


相对 于 Chrome 浏 览 器 ，Firefox 的 REST 插 件 功 能 类 似 ， 其 中 常用 的 插件 有 REST-Easy 和 RESTClient。REST-Easy 的 项 目地 址 是 : https://github.com/nathan-osman/REST-Easy，RESTClient 的 项 
地 址 是 : http://restclient.net。 


类 似 的 Firefox 插 件 比较 多 ， 读 者 如 果 有 兴趣 ， 可 以 通过 在 Firefox 浏 览 器 中 输入 about'addons 进 入 Firefox 的 扩展 ， 搜 索 更 多 的 相关 插件 。 


POSTMAN 


History Normal < Noenvironment™ 


中 
http://apiJlickrcomy/servicesy/rest/zmet @ http://apiflickr.com/: | GET 加 GUuRLparams | G Headers (0) 
hod=flickr.people.getinfo&api key=4d 三 


705e- Preview | Addtocollecton 


(3) Body FY 2000k BM 1026ms 


Pretty | Raw © Preview 二 | JSON | XML 


<2xml Version= "1.9”encoding= "utf-8” >> 
<rsp stat="ok"> 
<person id=" EEE nS id- qi 
<Uusername>feuyeux</username> 
<realname>Lu Han</realname> 
<location /> 
<timezone label="Beijing, Chongqing, Hong Kong, 
<description /> 
<photosurl>http: 
<profileurl>http: 
<mobileurl>http: 
<photos> 
<firstdatetaken>2811-88-27 11:23:43¢</firstda 
<firstdate>1315153536</firstdate> 
<count>245¢</count> 
</photos> 
</person> 


> 上 > 
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图 2-14 ”Postman-REST Client 插 件 示 意图 


2.7 本章 小 结 


本 章 全 面 讲 述 了 如 何 使 用 JAX-RS 2.0 的 参考 实现 Jersey 2.x 来 开发 REST 服 务 ， 并 提供 了 一 个 完整 的 REST 服 务 应 用 示例 和 流程 分 析 。 同 时 ， 介 绍 了 REST 开 发 过 程 中 的 调试 工具 。 其 中 ，2.1 节 分 析 了 基于 
Maven 构 建 的 Jersey 官 方 的 Java SE 例子 simple-service 并 基于 示例 实现 了 自 定义 资源 的 地 址 。2.2 节 分 析 了 基于 Servlet 环 境 的 Jersey 官 方 示例 simple-service-webapp， 并 演示 如 何在 Maven 插 件 、Servlet 
容器 和 Java EE 容器 中 运行 该 示例 。2.3 节 讲述 了 JAX-RS 2.0 的 Application 和 Servlet 的 4 种 存在 类 型 。2.4 节 讲述 了 WADL 以 及 Jersey 对 WADL 的 支持 。2.5 节 是 完整 示例 和 Jersey 处 理 REST 请 求 的 流程 分 析 。 
2.6 节 介绍 了 REST 请 求 的 3 组 调试 工具 。 


通过 本 章 的 讲述 ， 我 们 了 解 了 Jersey 开 发 的 全 金 ， 接 下 来 的 第 3 章 我 们 要 提高 一 个 层次 ， 掌 握 如 何 设 计 REST AP1， 以 使 我 们 的 REST 服 务 更 标准 和 健壮 。 


第 3 章 ”REST API 设 计 


设计 和 开发 REST 式 的 Web 服 务 除了 要 掌握 JAX-RS 2.0 标 准 ， 还 要 对 统一 接口 、 资 源 定位 以 及 请 求 处 理 过 程 中 REST 风 格 的 传输 数据 的 格式 、 响 应 信息 等 有 良好 的 认 知 。 此 外 ， 设 计 良好 的 REST API 应 当 
对 内 容 协商 、 资 源 地 址 信息 (link) 有 良好 的 支持 。 本 章 将 详细 讨论 这 些 技术 细节 。 


3.1 ”REST 统 一 接口 


REST 式 的 Web 服 务 和 RPC 式 的 Web 服 务 在 接口 定义 上 的 区 别 是 ，REST 使 用 HTTP 的 通用 方法 作为 统一 接口 的 标准 词汇 。REST 式 的 Web 服 务 所 提供 的 方法 信息 都 在 HTTP 方 法 里 ， 而 RPC 式 的 Web 服 务 所 
提供 的 方法 信息 在 SOAP/HTTP 信 封 里 (其 封装 的 格式 通常 是 HTTP 或 者 是 SOAP) ， 每 一 个 RPC 式 的 Web 服 务 都 会 公布 一 套 符合 自己 商业 逻辑 的 方法 词汇 。 


Oj 指南 3.1 节 示例 所 在 目录 是 jax-rs2-guide\sample\3\simple-service-3。 
源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : com.example.annotation.method。 


每 一 种 HTTP 请 求 方法 都 可 以 从 安全 性 和 客 等 性 两 方面 考虑 ， 这 对 正确 理解 HTTP 请 求 方法 和 设计 统一 接口 具有 决定 性 的 意义 。 换 句 话说 ， 要 定义 严谨 的 REST 统 一 接口 ， 就 需要 真正 理解 HTTP 方 法 的 安 
全 性 和 害 等 性 。 


安全 性 代表 安全 的 REST 接 口 ， 是 指 外 系统 对 该 接口 的 访问 ， 不 会 使 服务 器 端 资 源 的 状态 发 生 改 变 。 窜 等 性 (idempotence) 是 指 外 系统 对 同一 REST 接 口 的 多 次 访问 ， 得 到 的 资源 状态 是 相同 的 。 
图 阅读 指南 这 里 讨论 的 安全 性 对 应 的 英文 是 Safety 而 不 是 Security， 系 统 安全 可 参考 第 6 章 。 


以 下 ,将 从 REST 统 一 接口 的 定义 角度 ， 逐 个 讲述 HTTP 方 法 。 


3 名 方法 


REST 使 用 HTTP 的 GET 方 法 获取 服务 提供 的 资源 。GET 方 法 是 只 读 的 ， 那 么 它 是 朝 等 和 安全 的 吗 ” 答 案 马 上 揭晓 。 


1. 晕 等 性 和 安全 性 


HTTP 的 GET 方 法 用 于 读 取 资 源 。GET 方 法 是 盐 等 的 ， 因 为 读 取 同 一 个 资源 ， 总 是 得 到 相同 的 数据 。GET 方 法 也 是 安全 的 ， 因 为 读 取 资 源 不 会 对 其 状态 做 改动 。JAX-RS 2.0 指 出 了 @GET 注 解 对 资源 方法 
的 定义 ， 使 得 该 方法 用 于 处 理 GET 请 求 。 


值得 注意 的 是 ， 虽 然 GE 方法 的 特性 是 昭 等 和 安全 的 ， 但 这 不 意味 着 任何 一 个 定义 为 处 理 GET 请 求 的 方法 都 是 昭 等 和 安全 的 。 换 名 话说， 设计 不 良 的 API 有 可 能 违背 GET 的 特性 ,将 一 个 不 该 是 GET 的 方 
法 定义 为 之 。 


举 个 例子 ， 在 系统 B 中 设计 一 个 REST 的 AP1， 在 客户 端 调 用 时 读 取 系 统 A 中 x 类 型 的 数据 ， 然 后 将 A.x 与 系统 B 内 的 y 类 型 数据 做 比较 ， 如 果 两 个 集合 的 内 容 、 最 后 更 新 时 间 上 有 不 同 ， 需 要 执行 同步 数据 


即将 Ay 过 加 或 者 更 新 到 By 中 。 最 后 ， 将 同步 结果 信息 返回 给 向 系统 B 发 起 请 求 的 客户 端 ， 如 图 3-1 所 示 。 
2 获取 资源 - 电 


3 比较 并 同步 资源 


1 请 求 资源 一 其 
二 … 4 响应 资源 6 


REST 客 户 端 


图 3-1 请 求 资源 示意 图 


观察 图 3-1 左 侧 部 分 ， 这 是 一 个 获取 同步 信息 的 AP1， 因 此 这 个 API 的 设计 应 该 使 用 GET 请 求 方法 。 但 是 ， 稍 加 分 析 后 即 可 知道 该 场景 并 不 具备 使 用 GET 的 基本 条 件 。 因 为 同步 过 程 中 对 系统 B 内 的 资源 有 
写 操作 的 可 能 ， 因 此 不 具备 安全 性 ; 而 写 的 内 容 又 不 是 每 次 相同 ， 因 此 不 具有 震 等 性 。 所 以 ， 这 个 例子 应 该 定义 的 正确 的 请 求 方法 是 POST。 


2. 资 源 方法 命名 


不 妨 一 起 探讨 一 下 上 面 这 个 同步 信息 的 API 该 如 何 命名 ? 既然 是 同步 功能 ， 那 就 以 sync 一 类 的 字 根 作为 前 经， 这 样 所 有 的 同步 APl 都 具有 相同 的 开头 ,字迹 也 很 工整 。 遗 憾 的 是 ， 这 样 的 设计 并 不 符合 
REST 风 格 。 笔 者 的 理解 是 ， 从 字面 上 看 有 两 个 问题 : 第 一 ，sync 字 根 具 有 非 名 词性 的 含义 ， 从 ROA 角 度 上 看 ，sync 是 RPC 风 格 的 命名 : 动词 、 自 定义 方法 名 称 。 第 二 ， 这 样 命名 后 ， 资 源 名 称 从 一 个 主语 变 
成 了 宾语 ， 从 ROA 角 度 上 看 ， 面 向 的 不 再 是 资源 ， 而 是 要 执行 的 动作 。 


因此 ， 标 准 的 命名 方式 应 该 是 单数 的 同步 操作 以 资源 名 称 命名 ， 批 量 的 同步 操作 以 资源 名 称 的 复数 名 称 命名 。 比 如 这 个 API 是 用 于 同步 设备 的 ， 那 么 命名 可 以 使 用 device 和 devices。 如 果 担 心 与 普通 查 
询 业 务 资源 地 址 混淆 ， 那 么 可 以 在 资源 路 径 中 增加 查询 或 者 路 径 参数 ， 比 如 device/id=1&source=a_b、device/D/a/ 等 。 


3 .抽象 层 注解 资源 


JAX-RS 2.0 的 HTTP 方 法 注解 可 以 定义 在 接口 和 POJO 中 ， 置 于 接口 中 的 方法 名 上 更 具 抽 象 性 和 通用 性 。 示 例 代码 如 下 。 


@Path ("book") 
public interface BookResource { 


// 

关注 点 1 

: GET 

注解 从 抽象 类 上 移 到 接口 
@GET 


public String getWeight (); 
} 
public class EBookResourceImpl implements BookResource { 
/ 


关注 点 2 
: 实现 类 无 须 GET 
注解 


QOverride 
public String getWeight() { 
return "150M"; 


} 
public class GETTest extends JerseyTest { 
QOverride 
protected Application configure() { 
六 


关注 点 3 
: 加 载 的 是 实现 类 而 不 是 接口 


return new ResourceConfig (EBookResourceImpl .class); 
} 


@Test 
public void testGet() { 

Response response = target ("book") .request () .get (); 

Assert .assertEquals ("150M", response.readEntity (String.class)); 
} 


在 这 段 代 码 中 ， 资 源 接口 BookResource 定 义 了 一 个 GET 方 法 getWeight()， 这 个 方法 上 使 用 了 HTTP 方 法 注解 @GET， 见 关注 点 1。 资 源 接口 BookResource 的 实现 类 EBookResourcelmpl| 实 现 了 
getWeight0 方 法 ， 但 没有 再 次 使 用 @GET 注 解 。 也 就 是 说 ， 在 接口 中 抽象 地 定义 了 资源 的 请 求 方法 类 型 后 ， 其 全 部 实现 类 都 无 须 再 定义 。 这 使 得 编码 更 整洁 和 抽象 ， 见 关注 点 2。 


最 后 ， 需 要 注意 的 是 ， 在 测试 类 GETTest 中 注册 的 是 实现 类 EBookResourcelmpl 类 型 而 不 是 接口 BookResource 类 型 ， 见 关注 点 3。 


另外 ， 我 们 一 并 介绍 HEAD 方 法 和 OPTIONS 方 法 。 


HEAD 方 法 和 GET 方 法 相似 ， 只 是 服务 器 端的 返回 值 不 包括 HTTP 实 体 。 因 此 ，HEAD 方 法 是 安全 的 和 寡 等 的 。JAX-RS 2.0 定 义 了 @HEAD 注 解 来 定义 相关 资源 方法 。 


OPTIONS 方 法 和 GET 方 法 相似 ， 是 安全 的 和 盐 等 的 。OPTIONS 用 于 读 取 资源 所 支持 的 (Allow) 所 有 HTTP 请 求 方法 。JAX-RS 2.0 定 义 了 @OPTIONS 注 解 来 定义 相关 资源 方法 。 


342: 册 护 法 


PUT 方法 是 一 种 写 操作 的 HTTP 请 求 。REST 使 用 HTTP 的 PUT 方法 更 新 或 添加 资源 。 下 | 


1. 更 新 资源 


HTTP 的 PUT 方法 


为 了 解决 这 一 i 
方法 都 不 是 安全 的 。 


我 们 知道 ， 使 


同一 份 数据 了 。 


2. 添 加 资源 


而 创建 操作 通常 每 次 得 到 的 结果 是 不 同 的 ， 
都 会 为 数据 添加 一 个 新 的 3 
计 API， 即 客户 端 在 发 起 创建 请 求 时 ， 在 同一 份 数据 中 总 可 以 提供 唯一 的 主键 值 ， 服 务 器 不 会 对 其 进行 修改 ， 这 样 的 创建 请 求 确保 了 朝 等 性 ， 不 应 


服务 器 端 ， 


H 


， 何 时 该 使 用 POST 方法 。 


讲解 一 下 PUT 方法 的 作 


和 操作 时 的 媒体 类 型 。 


5 


同一 份 数据 向 服务 器 请 求 更 新 某 一 资源 ， 得 到 的 结果 应 该 总 是 相同 的 ， 


题 ， 我 们 首先 应 该 知道 PUT 方法 的 特性 。PUT 方 法 是 朝 等 的 ， 即 多 次 插入 或 者 更 新 同一 份 数 : 


因此 对 于 更 新 操作 ， 使 


因为 REST 只 是 风格 ， 不 是 技术 规范 /标准 ， 所 以 有 些 实现 REST 的 细节 没有 明确 的 定义 ， 这 对 实践 而 言 ， 不 可 避免 会 产生 某 些 误解 。 比 如 在 创建 和 更 新 某 个 资源 的 时 候 ， 开 发 者 比较 迷茫 的 是 何 时 该 有 


居 ， 在 服务 器 端 对 资源 状态 所 产生 的 改变 是 相同 的 。 PUT 方法 不 是 安全 的 ， 有 写 动作 的 HTTP 


因为 服务 器 端的 业务 层 逻 辑 通常 要 求 数据 的 


EF 键 值 ， 也 就 是 创建 一 个 


JAX-RS 2.0 定 义 了 @PUT 注 解 来 定义 相关 资源 方法 ， 示 例 代码 如 下 。 


@Path 
("book" 
) 


public interface BookResource { 


: 
注解 


法 定义 了 Produces 
内 和 Consumes 
加 


@Produces 


(MediaType 
) 


.TEXT_PLAIN 


@Consumes 


(MediaType 
) 


public 
(Book book 
); 
} 


.APPLICATION XML 


String newBook 


public class PutTest extends JerseyTest { 


public 
@Test 
public 


static AtomicLong clientBookSequence = new AtomicLong(); 


void testNew () 


{ 


final Book newBook = new Book 
(clientBookSequence.incrementAndGet ()， 
"book-" + System.nanoTime () 


是 


MediaType contentTypeMediaType = MediaType.APPLICATION XML TYPE; 
MediaType acceptMediaType = MediaType.TEXT PLAIN TYPE; 
final Entity<Book> bookEntity = Entity.entity 


(newBook, 


contentTypeMediaType 


final String lastUpdate = target 


("book" 
) .request 


(acceptMediaType 
) 


.Put 
(bookEntity, String.class 
下 这 


Assert .assertNotNull 
(lastUpdate 
); 


LOGGER .debug 
(lastUpdate 
); 


} 


在 这 段 代 码 


EF 键 字段 要 么 来 
E 键 值 不 同 的 新 资源 (如 果 没 有 业务 或 者 外 键 冲突 ) 。 所 以 ， 创 建 操作 通常 应 当 设计 为 POST 方法 的 


自 于 数据 库 的 主 


键 自 增 。 


自 增 一 个 逻辑 值 ， 要 么 来 


自 于 业务 平台 


再 使 用 POST 方法 。 


PUT 是 没有 疑问 的 。 可 能 读者 会 想到 最 后 更 新 时 间 字段 每 次 提交 会 不 同 ， 但 那 已 经 不 是 


此 ， 相 同 的 数据 每 一 次 提交 到 


API。 唯 有 一 种 场景 应 当 使 上 


PUT 方法 来 设 


该 方法 


中 ， 资 源 接 口 BookResource 使 用 @PUT 注 解 定义 了 newBook() 方 法 ， 上 有 


lastUpdate 使 


我 们 注意 到 


非 空 断言 ，lastUpdate 是 更 新 方法 newBook() 的 返回 实体 的 值 ， 代 表 最 后 更 新 时 


间 


于 处 理 相对 资源 路 径 为 “book” 的 PUT 请 求 ， 见 关注 点 1。 血 
惟 ， 见 关注 点 3。 


， 在 newBook() 方 法 上 ， 同 时 定义 了 @Produces (MediaType.TEXT_PLAIN) 注 


相关 的 媒体 类 型 知识 。 


3 .媒体 类 型 


PUT 方法 执行 写 操作 的 非 安 全 的 HTTP 方 法 ， 需 要 考虑 请 求实 体 媒体 类 型 和 响应 实体 媒体 类 型 。 请 求实 体 媒体 类 型 使 用 HTTP 头 的 Content Type 定义 ， 响 应 实体 媒体 类 型 使 


在 服务 器 端 ，@Consumes (MediaType.APPLICATION_XML) 定义 了 服务 器 端 要 消费 的 媒体 类 型 ， 即 消费 客 


产 的 媒体 类 型 ， 


客户 端 在 提交 非 安全 性 HTTP 请 求 方法 前 ， 在 Entity 类 的 实例 中 ， 定 义 该 Entity 实 例 的 媒体 类 型 ， 即 客户 端 请 求实 体 的 媒体 类 型 。Request() 方 法 用 于 定义 可 接收 的 HTTP 方 法 的 返 


即 服务 器 产生 的 响应 实体 的 媒体 类 型 。 


的 响应 实体 的 媒体 类 型 。 


测试 资源 方法 newBook()， 将 得 到 如 下 所 示 的 请 求 头 信息 ， 从 中 可 以 看 到 请 求 媒体 类 型 。 


public final static String TEXT _ PLAIN = "text/plain"; 


解 和 @Consumes (MediaType.APPLICATION_XML) 注解 ， 见 关注 点 2， 下 | 


元 测试 类 PutTest 对 


H 


我 们 来 介绍 一 下 与 关注 点 2 


HTTP 头 的 Accept 定 义 。 


户 端 请 求实 体 的 媒体 类 型 。@Produces (MediaType.TEXT_PLAIN) 定义 了 服务 器 端 生 


媒体 类 型 ， 即 服务 器 


public final static String APPLICATION XML = "application/xml"; 

public final static MediaType TEXT PLAIN TYPE = new MediaType ("text", "plain"); 

public final static MediaType APPLICATION XML TYPE = new MediaType ("application", "xml"); 
1 > PUT http://localhost:9998/book 

1 > Accept: text/plain 

1 > Content-Type: application/xml 


在 这 段 代 码 中 ，javax.ws.rs.core.MediaType 类 是 JAX-RS 2.0 提 供 的 媒体 类 型 定义 类 ， 其 中 定义 了 包括 示例 中 使 用 的 MediaType.TEXT_PLAIN， 其 值 为 “text/plain”。 在 MediaType 类 中 ， 对 应 的 响 
应 实体 媒体 类 型 定义 为 Accept:text/plain; MediaType.APPLICATION_XML 值 为 “application/xml”， 对 应 的 请 求实 体 媒 体 类 型 定义 为 Content-Type:application/xml。 


3.1.3 ”DELETE 方法 


DELETE 方 法 是 窜 等 的 ， 即 多 次 删除 同一 份 数 据 (通常 请 求 中 传递 的 参数 是 数据 的 主键 值 ) ， 在 服务 器 端 产生 的 改变 是 相同 的 。JAX-RS 2.0 定 义 了 @ DELETE 注 解 来 定义 相关 资源 方法 。 下 面 来 看 看 具体 
示例 。 


执行 删除 的 资源 方法 ， 其 返回 值 可 以 定义 为 void， 即 该 方法 没有 返回 值 。 之 所 以 在 删除 资源 的 场景 中 可 以 采用 这 样 的 方式 定义 ， 是 因为 删除 的 前 提 是 对 该 资源 信息 已 经 充分 了 解 ， 没 有 必要 再 将 其 从 服 
务 器 上 传递 回来 。 示 例 代码 如 下 。 


@Path ("book") 
public interface BookResource { 

@DELETE 

Public void delete (@QueryParam("bookId") final long bookId); 
} 


在 这 段 代码 中 ， 无 返回 值 的 资源 方法 delete() 返 回 的 响应 实体 为 空 ，HTTP 状 态 码 为 204。 该 定义 可 以 参考 Jersey 的 源 代码 中 的 Response 类 ， 示 例 代 码 如 下 。 


package javax.ws.rs.core; 
public abstract class Response { 
public interface StatusType { 
public enum Status implements StatusType { 
NO_CONTENT 
(204, "No Content" 
) 


’ 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
bs 


接 下 来 是 删除 资源 方法 的 单元 测试 ， 示 例 代 码 如 下 。 


public class DeleteTest extends JerseyTest { 
@Test 
public void testGet () { 
final Response response = 
target 
("book" 
) .queryParam 
("bookId", "9527" 
) .request () .delete(); 
int status = tesponse.getStatus () 7 
LOGGER .debug 
(status 
Assert .assertEquals 
(Response.Status.NO CONTENT.getStatusCode (), status 
); 


} 
bE 


在 这 段 代 码 中 ， 对 REST 请 求 的 测试 断言 不 是 针对 删除 资源 的 实体 ， 而 是 响应 中 HTTP 状 态 码 。 也 就 是 说 ， 删 除 资源 方法 的 返 


回 


值 类 型 可 以 定义 为 void， 业 务 逻 辑 更 关注 删除 操作 的 结果 状态 。 


3.14， POST 方法 


POST 方法 是 一 种 写 操作 的 HTTP 请 求 。RPC 的 所 有 写 操作 均 使 用 POST 方法 ， 而 REST 只 使 用 HTTP 的 POST 方法 添加 资源 。 


(1) 既 不 昧 等 也 不 安全 


定义 为 POST 的 REST 接 口 用 于 写 数据 。POST 方 法 的 特性 是 既 不 申 等 也 不 安全 。 因 为 请 求 会 改变 服务 器 端 资源 的 状态 ， 因 此 不 是 安全 的 ; 每 次 请 求 对 服务 器 端 资源 状态 的 改变 并 不 是 相同 的 ， 因 此 不 是 蝴 
等 的 。 


(2) 两 种 分 类 


REST 中 使 用 的 POST 可 以 称 为 POST (a) ， 即 用 于 创建 、 添 加 资源 的 HTTP 方 法 。 这 是 相对 于 RPC 式 的 Web 服 务 中 对 POST 的 使 用 而 言 的 。 


在 RPC 中 使 用 的 POST 可 以 称 为 POST (p) ， 即 通过 重 载 的 POST 用 于 处 理 某 种 操作 。 服 务 器 接收 POST (p) 的 请 求 后 ， 不 是 直接 处 理 POST 请 求 ， 真 正 的 方法 信息 位 于 信封 头 或 实体 主体 里 ， 因 此 需 
先 解析 出 执行 方法 。 


JAX-RS 2.0 定 义 了 @POST 注 解 来 定义 相关 资源 方法 ， 示 例 代 码 如 下 。 


@Path ("book") 
public interface BookResource { 


Q@POST 

@Produces (MediaType .APPLICATION XML) 

@Consumes (MediaType .APPLICATION XML) 

public Book createBook (Book book); 

public class PostTest extends JerseyTest { 

@Test 

public void testCreate() { 
final Book newBook = new Book ("book-" + System.nanoTime () ) 7 
MediaType contentTypeMediaType = MediaType.APPLICATION XML TYPE; 
MediaType acceptMediaType = MediaType.APPLICATION XML TYPE; 
final Entity<Book> bookEntity = Entity.entity (newBook, contentTypeMediaType); 
final Book book = 
target ("book") .request (acceptMediaType) .post (bookEntity, Book.class); 
// 


关注 点 2 

: 测试 POST 

方法 的 断言 
Assert .assertNotNull (book.getBookId()); 
LOGGER. debug ("Server Id="+book.getBookId()); 


在 这 段 代 码 中 ， 资 源 接口 BookResource 定 义 了 createBook() 方 法 ， 该 方法 使 用 @POST 注 解 表示 该 方法 处 理 “book” 路 径 下 的 POST 请 求 ， 见 关注 点 1。 在 测试 方法 testCreate( 中 ， 关 注 请 求 结果 实体 


的 主键 是 否 为 空 。 这 是 因为 在 POST 请 求 提交 的 添加 资源 操作 中 ， 


到 此 ， 我 们 完成 了 对 HTTP 的 基本 方法 的 讲述 。 除 了 HTTP 定 义 的 标准 方法 ， 还 存在 来 


3.1.5 ”WebDAV 扩展 方法 


E 键 的 设置 是 在 服务 器 端 完成 的 ， 


因此 客户 端 成 功 请 求 添加 资源 后 ， 应 关注 服务 器 端 返回 的 实体 结果 是 否 有 主键 信息 ， 见 关注 点 2。 


自 其 他 协议 中 的 HTTP 方 法 。 接 下 来 ， 我 们 一 起 探讨 这 些 方 法 对 REST 服 务 的 影响 。 


WebDAV (Web-based Distributed Authoring and Versioning， 基 于 Web 的 分 布 式 创作 与 版 本 控制 ) 是 IETF 的 RFC 4918 规 范 (RFC 2518 规 范 的 替代 规范 ， 地 址 在 


http://tools.ietf.org/html/rfc4918) ， 是 对 HTTP 1.1 的 一 组 扩 


“ PROPFIND 方 法 : 用 于 从 Web 资 源 中 查询 存储 为 XML 格 式 的 属性 数据 ， 或 者 重 载 为 从 一 个 远程 系统 中 查询 目录 结构 的 数据 。 


: PROPPATCH 方 法 : 用 于 原子 地 更 改 和 删除 一 个 资源 的 多 个 属性 。 


` MKCOL 方 法 : 用 于 创建 目录 。 


" COPY 方 法 : 用 于 将 资源 从 一 个 URI 资 源 地 址 复制 到 另 一 个 URI 资 源 地 址 。 


* MOVE 方 法 : 用 于 将 资源 从 一 个 URI 资 源 地 址 移动 到 另 一 个 URI 资 源 地 址 。 


' LOCK 方法 : 用 于 锁定 一 个 资源 。WebDAV 支 持 共享 锁 和 独占 锁 。 


“ UNLOCK 方 法 : 用 于 解锁 一 个 资源 。 


兵 


笔者 的 观点 是 如 果 遵 从 ROA， 那 么 就 不 使 用 HTTP 标 准 方法 之 外 的 方法 。 如 果 业 务 需求 确实 超出 了 标准 方法 所 及 ， 那 么 可 以 使 有 


展 ， 该 协议 允许 用 户 以 协作 方式 编辑 和 管理 远程 Web 服 务 器 上 的 文件 。WebDAV 在 HTTP 方 法 的 基础 上 ， 增 加 了 如 下 方法 。 


虽然 WebDAV 对 HTTP 方 法 做 出 了 功能 性 的 扩展 ， 使 之 提供 更 强大 的 服务 ， 但 是 从 ROA 角 度 讲 ，WebDAV 破 坏 了 统一 接口 的 原则 ， 因 为 WebDAV 在 HTTP 标 准 方法 的 基础 上 增加 了 特殊 的 方法 名 称 。 
对 是 否 应 该 在 REST 式 的 Web 服 务 中 支持 WebDAV， 业 内 的 观点 并 不 一 致 。 


加 


如 下 注解 实现 对 WebDAV 的 支持 。 


JAX-RS 2.0 规 范 没有 对 WebDAV 提 供 支持 的 描述 ， 但 是 JAX-RS 2.0 定 义 了 @ HttpMethod 注 解 来 定义 相关 的 资源 方法 。 在 Jersey 应 用 中 ， 可 以 使 


称 来 支持 WebDAV， 示 例 代码 如 下 。 


@Target ({ElementType .METHOD}) 
@Retention (RetentionPolicy.RUNTIME) 
@HttpMethod (value = "MOVE") 
@Documented 

public Qinterface MOVE { 

} 


这 段 代码 是 @ MOVE 注 解 的 定义 ， 使 用 @HttpMethod 注 解 定义 了 名 为 MOVE 的 HTTP 扩 


@Path ("book") 
public interface BookResource { 
QMOVE 
public boolean moveBooks (Books books); 


} 


@HttpMethod 注 解 定义 HTTP 标 准 方法 之 外 的 方法 名 


展 方法 。 有 了 扩 


在 这 段 代 码 中， 资源 类 BookResource 定 义 了 moveBooks() 方 法 ， 该 方法 使 用 @MOVE 注 解 定 义 ， 表 示 用 于 处 理 “book” 路 径 下 的 MOVE 请 求 。 


public class HttpMethodTest extends JerseyTest { 


QOverride 
protected Application configure() { 


ResourceConfig resourceConfig = new ResourceConfig (EBookResourceImpl .class); 


return resourceConfig; 


¥ 
QOverride 


protected void configureClient (ClientConfig clientConfig) { 


// 
关注 点 1 
: 定义 Grizzly 
连接 器 


clientConfig.connectorProvider (new GrizzlyConnectorProvider ()); 


super.configureClient (clientConfig); 


Q@Test 
Public void testWebDav() { 


final Response response = target ("book") .request () .method ("MOVE"); 
Boolean result = response.readEntity (Boolean.class); 


VE 
测 


: Move 
方法 测试 断言 


Assert .assertEquals (Boolean.TRUE, result); 


} 
} 


在 这 段 代码 中 ， 测 试 方法 testWebDav() 在 请 求 中 定义 了 MOVE 请 求 ， 见 关注 点 2。 断 言 是 针对 MOVE 方 法 的 返回 值 ， 见 关注 点 3。 可 以 看 出 ， 使 有 


需要 注意 的 是 ，Jersey 默 认 的 连接 器 只 支持 HTTP 标 准 方法 ， 因 
clientConfig.connectorProvider (new GrizzlyConnectorProvider0) ， 即 为 客户 端 配置 实例 提供 Grizzly 连 接 器 ， 见 关注 点 1。 这 行 代码 是 
clientConfig.connector (new GrizzlyConnector (clientConfig) ) 。 从 中 可 以 看 出 ，Jersey 在 不 断 优化 ， 包 括 API。 这 一 好 处 是 活跃 的 社 


兼容 性 。 


此 要 使 用 HTTP 的 扩 | 


展 方法 注解 ， 我 们 就 可 以 在 资源 类 中 定义 新 的 方法 来 支持 扩展 方法 的 请 求 了 。 示 例 代码 如 下 。 


下 面 我 们 来 看 看 相关 的 测试 代码 。 


Jersey 实 现 对 WebDav 的 支持 并 不 困难 。 


到 此 ， 我 们 全 面 掌握 了 HTTP 方 法 在 REST 统 一 接 


入 掌握 REST 的 资源 定位 。 接 下 来 一 节 将 详 述 资源 定位 | 


3.2 ”REST 资 源 定位 


定义 中 的 作 | 


的 细节 。 


和 实现 。 明 | 


了 REST 接 [ 


该 使 


展 方法 就 不 能 直接 使 用 默认 的 连接 器 ， 这 里 使 用 了 Grizzly 连 接 器 。 对 应 的 代码 行 是 : 
ersey 2.5+ 后 的 写法 ，Jersey 2.5 之 前 的 写法 是 
区 为 用 户 带 来 越 来 越 便捷 、 高 效 的 使 用 体验 ， 缺 点 是 破坏 了 向 下 


什么 样 的 请 求 方法 非常 重要 ， 这 决定 了 其 性 质 。 但 是 这 还 不 够 ， 一 个 接口 如 何 被 请 求 唯一 定位 还 需要 深 


REST 使 用 URI 实 现 资源 定位 ， 从 这 个 角度 上 讲 ， 对 外 提供 REST 式 的 Web 服 务 的 接 


将 URI 的 定义 随意 使 


在 设计 REST 式 的 Web 服 务 过 程 中 ， 资 源 地 址 的 设计 是 非常 严谨 的 ， 如 果 设 计 不 好 ， 不 仅 REST 接 


， 正 所 谓 “ 不 以 规矩 ， 不 成 方圆 ”。 


就 是 公布 一 系列 的 URI 及 其 参数 ， 这 使 得 REST 的 实践 过 程 简单 到 了 极致 。 但 是 URI 形 式 上 的 简单 并 不 意味 着 我 们 可 以 


的 风格 无 法 统一 ， 使 系统 的 扩展 性 和 易 


性 降低 ， 也 很 难 实现 资源 准确 地 被 定位 。 


资源 地 址 的 设计 过 程 是 面向 资源 的 ， 资 源 名 称 应 是 准确 描述 该 资源 的 名 词 ， 资 源 地 址 应 具有 直观 的 描述 性 。 比 如 一 个 班级 的 资源 地 址 可 以 是 : 学 校 /学 院 /学 级 /班级 。 值 得 注意 的 是 ， 一 个 URI 资 源 地 址 


唯一 对 应 一 个 资源 ， 但 是 一 个 资 


原 可 以 拥有 多 个 URI 资 源 地址 。 比 如 ，Jersey 最 新 版 本 的 文档 


也 址 和 Jersey 2.9 版 本 的 文档 地 址 指向 同一 个 资源 (笔者 撰 稿 时 ) 。 


Oj 指南 3.2 节 示例 所 在 目录 是 jax-rs2-guide\sample\3\simple-service-3。 


源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : com.example.annotation.param。 


3.2.1 


资源 地 址 的 设计 对 整个 REST 式 的 Web 服 务 至 关 重 


1. 资 源 路 径 概览 


资源 地 址 设计 


资源 地 址 的 路 径 变量 是 用 来 表达 逻辑 上 的 层次 结构 的 ， 资 
比如 一 个 生物 的 “ 门 、 纲 、 目 、 科 、 属 、 种 ”的 资源 路 径 。 资 


要 ， 涉 及 系统 的 可 上 


原 和 子 资源 的 形式 是 自 左 至 右 、 和 斜 杠 分 割 的 名 词 。 它 们 的 关系 可 以 是 从 整体 到 
原 地 址 具体 可 以 分 为 5 个 部 分 ， 见 表 3-1。 


性 、 可 维护 性 和 可 扩展 性 等 诸多 方 画 


的 表现 。 因 此 ， 本 节 关注 如 何 对 资源 地 址 进行 设计 。 


局 部 ， 比 如 学 校 到 班级 ， 洲 际 到 乡镇 ; 也 可 以 是 从 一 般 到 具体 ， 


表 3-1 资源 地 址 路 径 分 解 


Scheme 


host 
port 


path 
了 


queryString 


一 个 典型 的 URI 如 表 3-1 所 示 ， 包 括 协议 名 称 、 主 机 名 称 、 服 务 端 


scheme://host:port/path?queryString 
协议 名 称 。 通 常 是 HTTP 和 HTTPS 
(DNS) 主机 名 称 或 者 IP 地 址 
端口 
资源 地 址 ， 使 用 “/” 符 号 来 分 隔 逻 辑 上 的 层次 结构 
用 来 分 隔 资源 地 址 和 查询 字符 串 符 号 
查询 字符 串 ， 方 法 作用 域 信 息 
使 用 “人 ”符号 来 分 隔 查询 条 件 
使 用 逗号 分 隔 有 次 序 的 作用 域 信息 
使 用 分 号 分 隔 无 次 序 的 作用 域 信 息 


、 资 源 地 址 和 查询 字符 串 等 5 个 部 分 。 其 中 资源 地 址 部 分 ， 根 据 具 体 部 署 的 不 同 或 有 差别 ， 如 


3-2 所 示 。 


http://localhost:8080/simple-service-webapp-spring-jpa-jquery/webapi/books/book?id=1 


ContextPath ServletPath Pathinfo 
TD 


requestURI 


如 图 


注解 有 关 。 


3-2 所 示 ， 通 常 使 
名 称 ， 与 REST 服 务 中 定义 | 


现在 我 们 对 资源 地 址 的 


答案 是 否定 的 。 资 源 地 址 相同 ， 但 HTTP 方 法 不 同 的 两 个 方法 是 两 个 不 同 的 REST 接 
例 中 ，GET 方 法 用 于 读 取 / 检 索 、 查 询 


的 , 都 是 “book”。 


当 上 述 的 标准 的 HTTP 方 法 无 法 满足 
了 。 这 些 操作 是 动词 性 的 ， 无 法 简单 


地 使 


的 POST 方法 ， 辅 助 完成 复杂 业务 的 接口 
2 .资源 地 址 和 作用 域 

在 路 径 变 量 里 可 以 使 用 标点 符号 以 辅助 增强 逻辑 清晰 性 。 这 些 加 
对 资源 地 址 设计 至 关 重 要 的 符号 。 

1) “问号 ” (〈(?) 是 用 来 分 隔 资源 地 址 和 查询 字符 串 的 ，“ 与 ” 


屋 次 结构 有 了 初步 了 解 ， 此 时 需 


/过 滤 一 个 资源 ，PUT 方 法 


L 务 需求 时 ， 比 如 对 于 | 


图 书 资源 ， 除 了 基本 的 CRUD 之 外 ， 若 需要 公布 像 借阅 、 折 旧 、 电 子 版 下 载 等 实际 生活 中 的 更 新 操作 的 接口 时 ， 仅 公布 一 个 PUT 方法 就 不 够 
一 个 book 名 词 就 能 定位 。 在 路 径 变 量 难以 准确 描述 的 情况 下 ， 一 种 方案 是 可 以 考虑 使 用 动词 作为 查询 参数 ， 另 一 种 方案 是 可 以 在 REST 设 计 过 程 中 引入 RPC 风 格 
设计 ， 这 就 是 REST 和 RPC 混 合 型 的 Web 服 务 了 。 


于 修改 /更 新 资源 、 旬 


requestURI 


图 3-2 资源 地 址 示例 


ContextPath、ServletPath 和 Pathlinfo 来 细 分 资源 地 址 。ContextPath 是 上 下 文 名 称 ， 通 常 和 部 署 服 务 器 的 配置 或 者 REST 服 务 的 web.xml 配 置 有 关 。ServletPath 是 Servlet 的 
的 @ApplicationPath 注 解 或 者 Web.xml 的 配置 有 关 。JAX-RS 2.0 定 义 了 @Path 注 解 来 定义 资源 地 址 。Pathlnfo 是 资源 路 径 信息 ， 与 资源 类 、 子 类 以 及 类 中 的 方法 中 定义 的 @Path 


思考 一 个 问题 : 资源 地 址 是 否 可 以 唯一 定位 一 个 资源 ? 


。HTTP 方 法 和 资源 地 址 结合 在 一 起 才 可 以 完成 对 资源 的 定位 。 细 心 的 读者 也 许 从 3.1 节 的 示例 中 已 经 看 出 端倪 。 示 
建 客 户 端 维护 主键 信息 的 资源 ，DELETE 方 法 用 于 删除 资源 ，POST 方 法 用 于 创建 资源 。 但 这 些 方法 的 资源 地 址 是 相 


可 


有 助 符号 


在 表 3-2 中 的 查询 字符 串 ， 作 为 资源 地 址 的 查询 变量 ， 


来 表达 算法 的 输入 ， 实 现 对 方法 的 作 


域 的 约束 。 下 面 来 逐一 讲述 这 些 


(&) 符号 是 用 来 分 隔 查询 条 件 的 参数 的 。 示 例 代 码 如 下 。 


GET /books?start=0&size=10 


这 行 代码 的 作用 是 查询 图 书 列表 ， 开 始 行 参数 为 0， 条 目 参数 为 10， 即 从 第 0 行 开 始 取 10 条 信息 并 返回 该 图 书 列表 。 


2) “逗号 ” (，) 是 用 来 分 隔 有 次 序 的 作用 域 信 息 。 需 要 注意 的 是 ， 喜 号 分 隔 罗 辑 上 的 顺序 信息 ， 这 种 顺序 可 以 是 约定 俗 成 的 ， 比 如 先 写 经 度 后 写 纬度 ; 也 可 以 是 系统 约定 的 ， 比 如 “月 日 年 ”的 顺序 
等 。 举 例 来 说， 按时 间 区 间 查 询 图 书 ， 日 期 信息 在 资源 地 址 中 是 采用 “月 年 ”顺序 ， 示 例如 下 。 


GET /books/01,2002-12,2014 


这 行 代码 的 作用 是 查询 2002 年 1 月 ~2014 年 12 月 这 个 时 间 段 (出 版 ) 的 图 书 。 这 个 例子 中 还 使 用 了 “ 连 字符 ” (-) ， 有 时 候 也 可 以 使 用 “下 划 线 ” (_) 来 做 逻辑 上 的 辅助 分 隔 。 


3) “分 号 ” (; ) 是 用 来 分 隔 无 次 序 的 作用 域 信息 。 通 常 这 些 信息 是 逻辑 上 并 列 存在 的 ， 比 如 并 列 的 查询 条 件 ， 示 例如 下 所 示 。 


GET /books/restful;program=java;type=web 


这 行 代码 的 作用 是 查询 满足 图 书 内 容 为 RESTful 的 、 使 用 的 编程 语言 是 Java 的 、 讲 述 的 类 型 是 Web 的 图 书 列表 。 这 样 的 逻辑 没有 顺序 ， 互 换 顺 序 的 查询 条 件 不 会 影响 资源 的 表述 。 


基于 上 述 理论 ， 列 出 常用 的 资源 地 址 设计 示例 ， 见 表 3-2。 


表 3-2 资源 地 址 设计 


功能 资源 地 址 
POST /books 
添加 /创建 
加 / 创建 PUT /books/{id} 
删除 DELETE /books/fid} 
修改 /更 新 PUT /books/{id} 
查询 全 部 GET /books HTTP1.1 
i GET /books/{id} HTTP1.1 
主键 查 诊 
键 查 询 GET /books?id=12345678 
GET /books?start=0&size=10 
ee GET /books/01,2002-12,2014 
分 页 作用 域 查 询 


GET /books/restful;program=java;type=web 
GET /books?limit=]100&sort=bookname 


如 果 读者 可 以 轻松 领会 表 3-2 列 出 的 这 些 典 型 的 REST 接 口 和 资源 定位 的 设计 ， 就 可 以 放手 去 做 实现 的 事情 了 ， 和 否则 建议 回顾 本 节 内 容 。 接 下 来 ， 我 们 完成 从 设计 到 实现 的 跨越 ， 看 看 JAX-RS 2.0 标 准 是 
如 何 通过 注解 来 支持 资源 定位 的 ， 并 使 用 Jersey 完 成 上 述 设计 的 实践 。 


3.2.2 @QueryParam 注 解 


查询 条 件 决定 了 方法 的 作用 域 ， 查 询 参 数组 成 了 查询 条 件 。JAX-RS 2.0 定 义 了 @QueryParam 注 解 来 定义 查询 参数 ， 本 节 使 用 @QueryParam 演 示 3 个 REST 查 询 接口 的 实现 示例 ， 见 表 3-3。 


表 3-3”(@QueryParam 示 例 列表 


接口 描述 资源 地 址 
分 页 查询 列表 数据 /query-resource/yijings?start=24&size=10 
( 续 ) 
接口 描述 资源 地 址 
排序 并 分 页 查询 列表 数据 /query-resource/sorted-yijings?limit=5&sort=pronounce 
查询 单项 数据 /query-resource/yijing?id=8 


(1) 分 页 查询 


分 页 查询 是 使 用 @QueryParam 解 析 参 数 的 基本 示例 。 实 现代 码 如 下 所 示 。 


public Yijings getByPaging 
(@QueryParam 
("start™ 
) final int start, 
QQueryParam 
("size" 
) final int size 
} 40 
关注 点 1 
: 资源 方法 入 参 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
int listSize = globalList.size(); 
final int max = size > listSize ? listSize : size; 
a 
关注 点 2 
: 分 页 迭代 逻辑 
for 
(int i = 0, index = start; i < max; i++ 
) { 
final Yijing yijing = globalList.get 
(index + i 
: 


// 
关注 点 3 
: 添加 Link 


以 保证 REST 
的 连通 性 
final URI location = ub.clone () .queryParam 
("id", yijing.getSequence () 
) .build(); 
final Link link = 
new Link 
("detail", location.toASCIIString(), MediaType.APPLICATION XML 
人 


links.add 
(link 
); 
yijings.add 
(yijing 
); 
} 


result.setLinks 
(links 
); 
result .setGuas 
(yijings 
> 


return result; 


} 


在 这 段 代 码 中 ，getByPaging0) 方 法 的 输入 参数 包含 了 两 个 使 用 @QueryParam 注 解 定义 的 查询 参数 ， 分 别 是 起 始 条 目 参 数 “start” 和 条 目 数量 参数 “size”， 参 数 的 类 型 是 整 型 ， 见 关注 点 1。 在 查询 
的 迭代 中 使 用 这 两 个 参数 获取 图 书 列表 ， 见 关注 点 2。 在 迭代 中 ， 每 个 图 书 资源 条 目的 URI 都 存储 在 返回 值 中 ， 以 保证 资源 的 联通 性 ， 见 关注 点 3。 该 URI 被 封装 到 Link 实 例 中 ， 在 单项 查询 时 使 用 。 


另外 ， 参 数 的 定义 使 用 了 final， 符 合 Checkstyle 的 编程 风格 ， 即 输入 参数 只 作为 逻辑 算法 的 依据 使 用 ， 其 本 身 不 会 在 这 个 过 程 中 被 修改 。 也 许 这 种 不 变 的 变量 对 提高 执行 效率 并 没有 多 少 影响 ， 但 长 久 
来 看 效果 还 是 不 错 的 。 推 荐 Java 开 发 者 在 REST 开 发 中 引入 SonarQube 平 台 或 者 单纯 使 用 Checkstyle 工 具 对 静态 代码 进行 质量 检测 ， 以 帮助 我 们 改进 代码 的 质量 。 


(2) 排序 查询 


排序 查询 是 在 解析 参数 的 基础 上 ， 额 外 处 理 结果 集 顺序 的 示例 ， 代 码 如 下 。 


public Yijings getByOrder (QQueryParam("limit") final int limit, 
QQueryParam("sort") final String sortName) {// 
注 点 1 
: 资源 方法 入 参 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


Collections.sort (list, new Comparator<Yijing>() { 
QOverride 
// 


关注 点 2 
: 排序 中 的 比较 算法 
public int compare (final Yijing ol, final Yijing o2) { 
switch (sortName) { 
Case "sequence": 
return ol1.getSequence() .compareTo (02.getSequence ()); 
Case "name" : 
return ol1 .getName () .compareTo (o2.getName () ) 
Case "pronounce": 
return ol1.getPronounce () .compareTo (02.getPronounce()); 
} 


return 0; 


在 这 段 代 码 中 ，limit 参 数 的 用 途 同 分 页 查询 示例 ， 而 sortName 参 数 则 用 于 排序 ， 见 关注 点 1。 排 序 接口 需要 额外 解析 sortrName 传 递 的 排序 字段 ， 并 将 其 作为 数据 库 查 询 语句 中 的 排序 参数 使 用 。 这 里 
实现 了 Comparator 接 口 的 compare() 方 法 来 完成 根据 不 同 字段 对 集合 的 排序 ， 见 关注 点 2。 


(3) 单项 查询 


客户 端 在 获得 结果 集 的 基础 上 ， 根 据 表述 中 链接 信息 ， 向 服务 器 发 起 单项 查询 的 示例 ， 代 码 如 下 所 示 。 


public Yijing getByQuery (QQueryParam("id") final int seqId) { 
return ParamCache.find("" + seqId); 


i 


在 这 段 代 码 中 ， 使 用 @QueryParam 定 义 了 “id” 参 数 ， 该 参数 来 自分 页 查询 中 返回 的 URI 信 息 。 
3.2.3 @PathParam 注 解 


JAX-RS 2.0 定 义 了 @PathParam 注 解 来 定义 路 径 参 数 一 一 每 个 参数 对 应 一 个 子 资源 。 本 节 使 用 @PathParam 完 成 表 3-4 所 示 的 REST 查 询 接口 。 


表 3-4。”@PathParam 示 例 列表 


接口 描述 资源 地 址 


基本 路 径 参数 /path-resource/Eric 
结合 查询 参数 /path-resource/Eric ?hometown=Buenos Aires 


/path-resource/199-1999 
/path-resource/01,2012-12,2014 
了 资源 变 长 的 资源 路 径 /path-resource/Asia/China/northeast/liaoning/shenyang/huanggu 


/path-resource/q/restful;program=]java;type=web 


带 有 标点 符号 的 资源 路 径 


/path-resource/q2/restful;program=java;type=web 


1.@Path 注 解 


JAX-RS 2.0 定 义 了 @Path 注 解 来 定义 资源 路 径 ，@Path 接 收 一 个 value 参 数 ， 来 解析 资源 路 径 地 址 。 该 参数 除了 前 面 示例 中 的 books 这 种 静态 定义 的 方式 外 ， 也 可 以 使 用 动态 变量 的 方式 ， 其 的 格式 
为 : 侨 数 名 称 : 正则 表达 式 }。 这 个 接口 的 功能 和 查询 参数 实现 的 /query-resource/yijings?start=24&Lsize=10 相 似 ， 也 是 用 于 分 页 查询 ， 其 资源 地 址 形 如 : /path-resource/199-1999。 参 考 示 例如 下 。 


@GET 
Q@Path 
("{from:\\d+}-{to:\\d+}" 


) 
public String getByCondition 
(@PathParam 
Cfo 
) final Integer from, 
Q@PathParam 
Cnton 
) final Integer to 
) 4 
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在 这 段 代码 中 ， 使 用 @PathParam 注 解 定 义 的 两 个 参数 from 和 to 用 以 定义 查询 区 间 ， 正 则 表达 式 部 分 是 \d+ ， 表 示 数 字 。 两 个 参数 中 间 的 “连接 符 ” (-) 是 路 径 的 格式 信息 。 


稍 显 复杂 的 例子 是 : /path-resource/01，2012-12，2014， 引 入 了 逗号 (，) 作为 有 顺序 的 日 期 分 隔 符号 ， 那 么 对 应 的 正则 表达 式 为 : 


@Path 
(“{beginMonth:\\d+}, {beginYear:\\d+}-{endMonth:\\d+}, {endYear: \\d+} 
1) 


2. 正 则 表达 式 


正则 表达 式 的 内 容 超出 了 本 书 的 范围 ， 这 里 只 简 述 示例 中 用 到 的 正则 表达 式 。 刚 才 的 例子 中 的 \d+ ， 代 表 参 数 应 为 数字 并 且 至 少 出 现 一 次 。 第 一 个 反 斜 杠 是 Java 中 的 转 义 字符 ， 第 二 个 反 斜 杠 是 正则 表 
达 式 的 起 始 ， 加 号 (+) 是 至 少 出 现 一 次 的 意思 ， 星 号 (*) 则 代表 出 现 至 少 零 次 ， 句 号 (.) 是 匹配 任何 字符 ，d 是 匹配 数字 ，w 是 匹配 数字 和 字母 。 


示例 中 使 用 的 正则 表达 式 见 表 3-5 所 示 ， 读 者 掌握 所 说 明 的 路 径 含义 即 可 ， 我 们 的 目的 是 学 习 REST Apl 设 计 ， 而 非 正则 表达 式 本 身 。 
表 3-5 正则 表达 式 示例 
正则 表达 式 含义 
[a-zA-Z][a-zA-Z_0-9]* 以 字母 开头 ， 后 面 是 零 到 多 个 “字母 “数字 ”格式 的 字符 组 合 
region 变量 至 少 包含 一 个 任意 字符 
district 变量 至 少 包含 一 个 为 数字 或 者 字母 的 字符 


{region:.+}/{district:\w+} 


3. 路 径 配 合 查询 


查询 参数 和 路 径 参数 在 一 个 接口 中 配合 使 用 ， 可 以 更 快捷 地 完成 资源 定位 ， 这 很 像 战 场 上 的 多 兵种 协同 作战 。 前 述 的 图 书 资源 的 复杂 设计 就 需要 两 者 结合 来 完成 ， 示 例 代码 如 下 。 


@Path("{user: [a-zA-2] [a-zA-2 0-9]*}") 

@Produces (MediaType.TEXT PLAIN) 

public String getUserInfo (@PathParam("user") final String user, 

@DefaultValue ("Shen Yang")@QueryParam("hometown") final String hometown) { 
return user + ":" + hometown; 


} 


在 这 段 代 码 中 ， 路 径 参数 user 中 使 用 了 通配符 ， 方 法 参数 中 同时 使 用 @PathParam 注 解 和 @QueryParam， 定 义 了 user 和 hometown 两 个 参数 。 以 资源 地 址 : /path-resource/Eric? 
hometown=Buenos Aires 为 例 ，REST 容 器 会 将 该 请 求 匹配 到 getUserlnfo() 方 法 ， 其 中 Eric 是 路 径 变量 user 的 值 ，Buenos Aires 作 为 查询 变量 hometown 的 值 。 


4 路径 区 间 


路 径 区 间 (PathSegment) 是 对 资源 地 址 更 灵活 的 支持 ， 使 资源 类 的 一 个 方法 可 以 支持 更 广泛 的 资源 地 址 的 请 求 。 我 们 以 下 面 定义 的 资源 地 址 列表 来 了 解 PathSsegment。 


/path-resource/Asia/China/northeast/liaoning/shenyang/huanggu 
/path-resource/China/northeast/liaoning/shenyang/tiexi 
/path-resource/China/shenyang/huanggu 


如 上 所 示 的 资源 地 址 中 含有 固定 子 资源 (shenyang) 和 动态 子 资源 两 部 分 。 对 于 动态 匹配 变 长 的 子 资源 资源 地 址 ，PathSegment 类 型 的 参数 结合 正则 表达 式 将 发 挥 很 大 的 作用 。 示 例 代 码 如 下 。 


@GET 
@Path ("{region: .+}/shenyang/{district:\\wt}") 
public String getByAddress (@PathParam("region") final List<PathSegment> region, 
@PathParam("district") final String district) { 

final StringBuilder result = new StringBuilder(); 

for (final PathSegment pathSegment : region) { 

result .append (pathSegment .getPath () ) .append ("-") 7 
* 


result .append ("shenyang-" + district); 
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在 这 段 代 码 中 ，getByAddress() 方 法 用 来 匹配 表 的 这 些 资源 地 址 。 该 方法 的 region 变 量 是 Pathsegment 类 型 的 数组 ， 以 匹配 至 少 出 现 一 个 字符 的 正则 表达 式 (.+) 。PathSegment 如 其 名 字 所 示 ， 是 
路 径 的 片段 ， 是 子 资源 的 集合 。 遍 历 PathSegment 集 合 ， 对 于 每 一 个 PathSegment 实 例 ， 可 以 通过 调用 其 getPath 方 法 获取 子 资源 名 称 。 


对 于 查询 参数 动态 给 定 的 场景 ， 可 以 定义 PathSegment 作 为 参数 类 型 ， 通 过 getMatrixParameters() 方 法 获取 MultivaluedMap 类 型 的 查询 参数 信息 ， 即 可 将 参数 条 件 作 为 一 个 整体 解析 。 示 例 代 码 如 
"Rs 


@Path ("gq/ {condition}") 
public String getByCondition3 (@PathParam("condition") final PathSegment condition) { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
final MultivaluedMap<String, String> matrixParameters = condition.getMatrixParameters () 7 
final Iterator<Entry<String, List<String>>> 
iterator = matrixParameters.entrySet () .iterator () 
while (iterator.hasNext()) { 
final Entry<String, List<String>> entr 
conds.append (entry.getKey ()) .append ("= 
conds.append (entry.getValue () ) .append ( 


iterator.next (); 


} 
return conds.tostring(); 


} 


在 这 段 代 码 中 ，getByCondition3() 方 法 只 有 一 个 PathSegment 类 型 的 参数 condition， 该 参数 包含 了 查询 条 件 中 携带 的 全 部 参数 列表 。 举 例 来 说 ， 资 源 地 址 为 “path- 
resource/q/restful;program=java;type=web” 的 请 求 可 以 匹配 getByCondition30 方 法 ， 其 中 ，Multivalued Map 类 型 的 实例 matrixParameters 的 值 为 “[program=[java], type=[web]]”。 


5.@MatrixParam 注 解 


PathSegment 类 的 getMatrixParameters() 方 法 来 获取 查询 参数 信息 。 还 有 一 种 方式 是 通过 @ MatrixParam 注 解 来 逐一 定义 参数 ， 即 通过 声明 方式 来 获取 。 示 例 代码 如 


上 例 中 ， 通 过 编程 方式 ， 调 
下 。 


@Path ("q2/{fcondition}") 
public String getByCondition4 (@PathParam("condition") 
final PathSegment condition, @MatrixParam("program") final String program, 
@MatrixParam("type") final String type) { 
return condition.getPath() + " program=[" + program + "] type=[" + type + "]"; 
} 


在 这 段 代码 中 ， 使 用 @MatrixParam 注 解 分 别 定义 了 “program” 和 “type” 两 个 参数 。 与 上 例 相 比 ， 这 段 代 码 更 加 清晰 地 表达 了 可 接收 的 参数 名 称 和 类 型 ， 缺 点 是 缺乏 对 请 求 资源 地 址 更 灵活 的 支 


持 。 


3.24 @FormpParam 注 解 


以 处 理 请 求实 体 媒体 类 型 为 Content-Type:application/x-www-form-urlencoded 的 请 求 。 示 例 代 码 如 下 。 


JAX-RS 2.0 定 义 了 @FormParam 注 解 来 定义 表单 参数 ， 相 应 的 REST 方 法 


@Path ("form-resource") 
public class FormResource { 
Q@POST 
public String newPassword( 

@DefaultValue ("feuyeux") @FormParam(FormResource.USER) final String user, 

@Encoded @FormParam (FormResource.PW) final String password, 

@Encoded QFormParam (FormResource.NPW) final String newPassword, 

@FormParam (FormResource.VNPW) final String verification) { 
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中 | 


3-3 所 示 。 


在 这 段 代 码 的 newPassword() 方 法 中 ，@FormpParam 注 解 定义 了 user 等 4 个 参数 ， 这 些 参数 是 容器 从 请 求 中 获取 并 匹配 的 。 相 关 的 客户 端 测 试 如 
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POSTMAN 局 9 


POST BG Headers (0) 
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http-Wlocalhost-8080/simple-service-3/w 
ebapi/formresource 
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form-data 


x-www-form-urlencoded raw 


BG URL params 


USer 


enc 


password 
newPassword 
verification 

Key 

Preview 


Send Add to collection 


2000K Da 159ms 


Body 


Pretty | Raw | Prevew mm 计 JSON | XML 


1 eric:1qa2ws:1qa2ws:9527 


图 3-3 表单 示例 


Posman 定 义 的 基本 表单 信息 与 newPassword() 方 法 一 致 。 


网 


3-3 所 示 的 客户 端 工具 是 Postman ( 详 见 2.6 节 ) ， 使 


newPassword() 方 法 的 测试 代码 片段 如 下 。 


QTest 
public void testPost2() { 
final Form form = new Form(); 
form.param (FormResource.USER, "feuyeux"); 
form.param (FormResource.PW, " 
北京 "); 
form.param (FormResource.NPW, 
上 海 "); 
form.param (FormResource .VNPW, 
上 海 "); 
final String result = target ("form-resource") .request () . 
post (Entity.entity (form, MediaType.APPLICATION FORM URLENCODED TYPE), String.class); 
FormTest .LOGGER. debug (result); 
Assert .assertEquals ("encoded should let it to disable decoding", 
"feuyeux: SE5%8C%97%E4%BASAC: SEA%SB8%8ASE6SBS%B7 : 
上 海 "，result); 
} 


在 这 段 代 码 中 ，Form 类 实例 是 请 求实 体 ， 请 求实 体 的 类 型 为 MediaType.APPLICATION_FORM_URLENCODED TYPE， 即 application/x-www-form-urlencoded。 


这 里 还 需要 注意 的 是 @Encoded 注 解 和 @ DefaultValue 注 解 的 使 用 。 


JAX-RS 2.0 定 义 了 @ Encoded 注 解 用 以 标识 禁用 自动 解码 。 示 例 的 测试 结果 中 “%E4%B8%8A%E6%B5%B7” 是 newPassword() 的 参数 值 “ 上 海 ” 的 编码 值 ， 当 对 newPassword0 使 用 @Encoded 注 
解 时 ，REST 方 法 得 到 的 参数 值 就 不 会 被 解码 ， 如 果 将 其 直接 返回 ， 那 么 客户 端 得 到 的 值 就 会 是 处 于 编码 状态 的 字符 


D0 


JAX-RS 2.0 定 义 了 @ DefaultValue 注 解 用 以 为 客户 端 没有 为 其 提供 值 的 参数 提供 默认 值 。 本 例 的 user 参 数 的 默认 值 为 feuyeux。 


3.2.5”@BeanParam 注 解 


JAX-RS 2.0 定 义 了 @BeanParam 注 解 


于 自 定义 参数 组 合 ，BeanParam 使 得 REST 方 法 可 以 使 用 简洁 的 参数 形式 完成 复杂 的 接口 设计 。@BeanParam 注 解 的 使 用 示例 如 下 所 示 。 


@GET 

@Path ("{region: .+}/shenyang/ {district:\\wt}") 

public String getByAddress (@BeanParam Jaxrs2GuideParam param) {// 
1 


关注 

: 方法 入 参 

// 

关注 点 2 

: 参数 组 合 

public class Jaxrs2GuideParam { 
@HeaderParam ("accept") 
Private String acceptParam; 
@PathParam ("region") 
private String regionParam; 
Q@PathParam("district") 
private String districtParam; 
QQueryParam ("station") 
private String stationParam; 
QQueryParam ("vehicle") 
Private String vehicleParam; 

public void testBeanParam() { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


final WebTarget queryTarget = target (path) .path ("China") .path ("northeast") 
.Path ("shenyang") .path ("tiexi") 
.queryParam ("station", "Workers Village") .queryParam("vehicle", "bus"); 
result = queryTarget.request () .get () .readEntity (String.class); 
// 

关注 点 3 

: 查询 结果 断言 
Rssert.assertEquals ("China/northeast:tiexi:Workers Village:bus", result); 


} 


df 
关注 点 4 
: 复杂 的 查询 请 求 


http://localhost:9998/ctx-resource/China/shenyang/tiexi?station=Workers+Village&vehicle=bus 


在 这 段 代 码 中 ，getByAddress() 方 法 只 有 了 一 个 使 用 @BeanParam 注 解 定义 的 Jaxrs2-GuideParam 类 型 的 参数 ， 见 关注 点 1。Jaxrs2GuideParam 类 定义 了 一 系列 REST 方 法 会 用 到 的 参数 类 型 ， 包 括 示 
例 中 使 用 的 查询 参数 “station” 和 路 径 参 数 “region” 等 。 从 而 使 得 getByAddress() 方 法 可 以 匹配 更 为 复杂 的 资源 路 径 ， 见 关注 点 2。 在 变 长 子 资源 的 例子 基础 上 ， 增 加 了 查询 条 件 ， 但 从 测试 方法 


testBeanParam() 发 起 的 请 求 的 资源 地 址 ( 见 关注 点 4) 可 以 看 出 ， 这 是 一 个 较为 复杂 的 查询 请 求 ， 其 中 路 径 部 分 包括 China/shenyang/tiexi， 查 询 条 件 包括 station=Workers+Village 和 vehicle=bus。 这 


些 条件 均 在 Jaxrs2GuideParam 类 中 可 以 匹配 ， 因 此 从 关注 点 3 的 测试 断言 中 可 以 看 出 ， 该 请 求 的 响应 的 预期 结果 是 “China/northeast:tiexi:-Workers Village:bus”。 


3.2.6”@CookieParam 注 解 


JAX-RS 2.0 定 义 了 @CookieParam 注 解 用 以 匹配 Cookie 中 的 键 值 对 信息 ， 示 例 代 码 如 下 。 


@GET 

public String getHeaderParams (QCookieParam("longitude") final String longitude, 
Q@CookieParam("latitude") final String latitude, 
Q@CookieParam("population") final double population, 
@CookieParam("area") final int area) {// 

关注 点 1 

源 方法 入 参 


六 


return longitude + "," + latitude + " population=" + population + ",area=" + area; 


Q@Test 
Public void testContexts () { 
final Builder request = target (path) .request (); 
request .cookie ("longitude", "123.38"); 
request .cookie ("latitude", "41.8"); 
request .cookie ("population", "822.8"); 
request .cookie ("area", "12948"); 
result = request .get () .readEntity (String.class); 
// 
关注 点 2 
: 测试 结果 断言 
Rssert.assertEquals ("123.38,41.8 population=822.8,area=12948", result); 
} 


在 这 段 代码 中 ，getHeaderParams() 方 法 包含 4 个 使 用 @CookieParam 注 解 定 义 的 参数 ， 
键 值 对 信息 ， 其 断言 是 对 cookie 字 段 值 的 验证 ， 见 关注 点 2。 


3.2.7 @Context 注 解 


于 


匹配 Cookie 的 字段 ， 见 关注 点 1。 在 测试 方法 testContexts() 中 ， 客 户 端 Builder 实 例 填充 了 相应 的 cookie 


JAX-RS 2.0 定 义 了 @Context 注 解 来 解析 上 下 文 参数 ，JAX-RS 2.0 中 有 多 种 元 素 可 以 通过 @Context 注 解 作为 上 下 文 参数 使 用 。 示 例 代 码 如 下 。 


public String getByAddress( 
@Context final Application application, 
@Context final Request request, 
QContext final javax.ws.rs.ext.Providers provider, 
QContext final UriInfo uriInfo, 
@Context final HttpHeaders headers){ 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


} 


在 这 段 代 码 中 ， 分 别 定义 了 Application、Request、Providers、Urilnfo 和 HttpHeaders 等 5 种 类 型 的 上 下 文 实例 。 从 这 些 实例 中 可 以 获取 请 求 过 程 中 的 重要 参数 信息 ， 示 例 代 码 如 下 。 


final MultivaluedMap<String，String> pathMap = uriTnfo.getPathParameters () 
final MultivaluedMap<String，String> queryMap = uriInfo.getQueryParameters () ; 
final List<PathSegment> segmentList = uriInfo.getPathSegments (); 

final MultivaluedMap<String，String> headerMap = headers.getRequestHeaders (); 


在 这 段 代 码 中 ，Urilnfo 类 是 路 径 信息 的 上 下 文 ， 从 中 可 以 获取 路 径 参数 集合 getPath-Parameters(0 和 查询 参数 集合 getQueryParameters()。 类 似 的 ， 我 们 可 以 从 HttpHeaders 类 中 获取 头 信息 集合 
getRequestHeaders(0。 这 些 业务 逻辑 处 理 中 常用 的 辅助 信息 的 获取 ， 通 过 @Context 注 解 定义 方法 的 参数 或 者 类 的 字段 来 实现 。 


到 此 ， 我 们 已 经 对 统一 接口 和 资源 定位 的 设计 和 实现 讲述 完毕 。 但 是 ， 设 计 REST 接 口 还 需要 在 此 基础 上 ， 掌 握 请 求实 体 和 响应 实体 的 传输 格式 。 接 下 来 ， 让 我 们 看 看 Jersey 都 支持 哪些 类 型 的 传输 格 


式 。 


3.3 ”REST 传 输 格 式 


本 节 要 考虑 的 就 是 如 何 设计 表述 ， 即 传输 过 程 中 数据 采用 什么 样 的 数据 格式 。 通 常 ，REST 接 口 会 以 XML 和 JSON 作 为 主要 的 传输 格式 ， 这 两 种 格式 数据 的 处 理 是 本 节 的 


点 。 那 么 Jersey 是 否 还 支持 其 


他 的 数据 格式 呢 ? 答案 是 肯定 的 ， 让 我 们 逐一 掌握 各 种 类 型 的 实现 。 


3.3.1 基本 类 型 


Java 的 基本 类 型 又 叫 原生 类 型 ， 包 括 4 种 整 型 (byte、short、int、long) 、 两 种 浮 点 类 型 (float、double) 、 


@@ 阅 读 指南 3.3 节 的 前 4 小 节 示 例 所 在 目录 是 : jax-rs2-guide\sample\3\simple-service-3。 
源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : 


com.examble.response。 


Jersey 支 持 全 部 的 基本 类 型 ， 还 支持 与 之 相关 的 引 
代码 如 下 。 


Unicode 编 码 的 字符 (char) 和 布尔 类 型 (boolean) 。 


类 型 。 前 述 示例 已 经 呈现 了 整 型 (int) 等 Java 的 基本 类 型 的 参数 ， 本 例 将 展示 字 节 数组 类 型 作为 请 求实 体 类 型 、 字 符 串 作 为 响应 实体 类 型 的 示例 ， 


Q@POST 
Q@Path ("b") 
public String postBytes (final byte[] bs) {// 
关注 点 1 
: 测试 方法 入 参 
for (final byte b : bs) { 
LOGGER. debug (b) ; 
} 
return "byte[]:" + new String (bs); 
} 
Q@Test 
public void testBytes () { 
final String message = "TEST STRING"; 
final Builder request = target (path) .Path ("b") .request (); 
final Response response = request.post( 
Entity.entity (message, MediaType.TEXT PLAIN TYPE), Response.class); 
result = response.readentity (String.class); 
// 
关注 点 2 
: 测试 断言 
Assert.assertEquals ("byte[]:" + message, result); 
} 


在 这 段 代码 中 ， 资 源 方法 postBytes() 的 输入 参数 是 byte[ 类 型 ， 输 出 参数 是 String 类 型 ， 见 关注 点 1。 单 元 测试 方法 testBytes() 的 断言 是 对 字符 串 “TEST STRING” 的 验证 ， 见 关注 点 2。 


3.3.2 ”文件 类 型 


Jersey 支 持 传输 File 类 型 的 数据 ， 以 方便 客户 端 直 接 传递 File 类 实例 给 服务 器 端 。 文 件 类 型 的 请 求 ， 默 认 使 用 的 媒体 类 型 是 Content-Type:text/html。 示 例 代 码 如 下 。 


@POST 
@Path ("f") 
A 


点 
: 测试 方法 入 参 
public File postFile(final File f) throws FileNotFoundException, IOException { 


i 
关注 点 2 
: try-with-resources 
try (BufferedReader br = new BufferedReader (new FileReader (f))) { 
String s; 
dof{ 


Ei 


s = br.readLine(); 
LOGGER. debug (s); 
} while (s != null); 
return f; 
F 
} 
@Test 
public void testFile() throws FileNotFoundException, IOException { 


J 
关注 点 3 
: 获取 文件 全 路 径 


final URL resource = getClass() .getClassLoader () .getResource ("gua.txt"); 


final String file = resource.getFile(); 
final File f = new File(file); 
final Builder request = target (path) .Path ("f") .request (); 


请 求 
Entity<File> e = Entity.entity (f, MediaType.TEXT PLAIN TYPE); 
final Response response = request.post (e, Response.class); 
File result = response.reaqEntity (File.class); 
try (BufferedReader br = new BufferedReader (new FileReader (result))) { 
String S7 
dof{ 


关注 点 6 
: 逐 行 读 取 文件 
LOGGER. debug (s); 
} while (s != null); 
} 
} 


s = br.readLine();// 


在 这 段 代 码 中 ， 资 源 方法 postFile() 的 输入 参数 类 型 和 返回 值 类 型 都 是 File 类 型 ， 见 关注 点 1。 服 务 器 端 对 File 实 例 进 行 解析 ， 最 后 将 该 资源 释放 ， 即 try-with-resources， 见 关注 点 2。 在 测试 方法 
testFile0 中 ， 构 建 了 File 类 型 的 “gua.txt” 文 件 的 实例 ， 见 关注 点 3， 作 为 请 求实 体 提交 ， 见 关注 点 4， 并 对 响应 实体 进行 逐 行 读 取 的 校 验 ， 见 关注 点 5。 


需要 注意 的 是 ， 由 于 我 们 使 用 的 是 Maven 构 建 的 项 目 ， 测 试 文件 位 于 测试 
getClass().getClassLoader().getResource ("gua.txt") ， 见 关注 点 6。 


另外 ， 文 件 的 资源 释放 使 


了 JDK 7 的 try-with-resources 语 法 ， 见 关注 点 2。 


3.3.3 Inputstream 类 型 


Jersey 支 持 Java 的 两 大 读 写 模式 ， 即 字 节 流 和 字符 流 。 本 示例 展示 字 节 流 作为 REST 方 法 参数 ， 代 码 如 下 。 


@POST 
@Path ("bio") 
ZY 


录 的 resources 目 录 ， 其 相对 路 径 为 /simple-service-3/src/test/resources/gua.txt， 获 取 该 文件 的 语句 为 


关注 点 1 
: 资源 方法 入 参 
public String PostStream(final InputStream is) throws FileNotFoundException, IOException { 


// 
关注 点 2 
: try-with-resources 
try (BufferedReader br = new BufferedReader (new InputStreamReader (is))) { 
StringBuilder result = new StringBuilder (); 
String s = br.readLine(); 
while (s != null) { 
result .append (s) .append ("\n"); 
LOGGER. debug (s); 
s = br.readLine(); 
} 
return result.toString();// 
关注 点 3 
: 资源 方法 返回 值 
} 
} 
@Test 
public void testStream() { 
人 
关注 点 4 
: 获取 文件 全 路 径 


final InPutStream resource = getClass () .getC1assLoader () .getResourceAsStream("gua.txt"); 
final Builder request = target (path) .path ("bio") .request () 
Entity<InputStream> e = Entity.entity (resource, MediaType.TEXT PLAIN TYPE) ， 
final Response response = request.post(e, Response.class); 
result = response.readEentity (String.class); 
i 
关注 点 5 
: 输出 返回 值 内 容 
LOGGER.debug (result); 
} 


在 这 段 代码 中 ， 资 源 方法 postStream() 的 输入 参数 类 型 是 Inputstream， 见 关注 点 1， 服 务 器 端 从 中 读 取 字 节 流 ， 并 最 终 释 放 该 资源 ， 见 关注 点 2， 返 回 值 是 String 类 型 ， 内 容 是 字 节 流 信息 ， 见 关注 点 
3。 测 试 方法 testStream0 构 建 了 “gua.txt” 文 件 内 容 的 字 节 流 ， 作 为 请 求实 体 提交 ， 见 关注 点 4。 响 应 实体 预期 为 String 类 型 的 “gua.txt” 文 件 内 容 信 息 ， 见 关注 点 5。 


3.3.4 ”Reader 类 型 


本 示例 展示 另 一 种 Java 读 写 模式 ， 以 字符 流 作为 REST 方 法 参数 ， 代 码 如 下 。 


Q@POST 
@Path ("cio") 


这 
关注 点 1 
: 资源 方法 入 参 
public String postChars (final Reader r) throws FileNotFoundException, IOException { 
// 
关注 点 2 
: try-with-resources 
try (BufferedReader br = new BufferedReader (r)) { 
String s = br.readLine(); 
if (s = null) { 
throw new Jaxrs2GuideNotFoundException ("NOT FOUND FROM READER"); 
: 
while (s != null) { 
LOGGER. debug (s); 
s = br.readLine(); 
‘ 
return "reader"7 
} 
i 
QTest 
public void testReader() { 
// 
关注 点 3 
: 构建 并 提交 Reader 
实例 
ClassLoader classLoader = getClass () .getClassLoader (); 
final Reader resource = 
new InputStreamReader (classLoader.getResourceAsStream("gua.txt")); 
final Builder request = target (path) .path ("cio") .request (); 
Entity<Reader> e = Entity.entity (resource, MediaType.TEXT PLAIN TYPE); 
final Response response = request.post(e, Response.class); 
result = response.readentity (String.class); 


// 
关注 点 4 
: 输出 返回 值 内 容 


LOGGER.debug (result); 
} 


在 这 段 代 码 中 ， 资 源 方法 postChars() 的 输入 参数 类 型 是 Reader， 见 关注 点 1， 服 务 器 端 从 中 读 取 字 符 流 ， 并 最 终 释 放 该 资源 ， 见 关注 点 2， 返 回 值 是 string 类 型 。 测 试 方法 testReader() 构 建 
了 “guatxt” 文 件 内 容 的 Reader 实 例 ， 将 字符 流 作为 请 求实 体 提交 ， 见 关注 点 3。 响 应 实体 预期 为 String 类 型 的 “gua.txt” 文 件 内 容 信 息 ， 见 关注 点 4。 


3.3.5 ”XML 类 型 


XML 类 型 是 使 用 比较 广泛 的 数据 类 型 。Jersey 对 XML 类 型 的 数据 处 理 ， 支 持 Java 领 域 的 两 大 标准 ， 即 JAXP (Java API for XML Processing) 和 JAXB (Java Architecture for XML Binding, JSR- 
222) 。 


@@ 阅 诬 指 南 本 小 节 示 例 所 在 目录 是 : jax-rs2-guide\sample\3\simple-service-3。 
源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : com.example.media.xml。 


1JAXP 标 准 
“JAXP 包 含 了 DOM、SAX 和 StAX 三 种 解析 XML 的 技术 标准 。 
" DOM 是 面向 文档 解析 的 技术 ， 要 求 将 XML 数 据 全 部 加 载 到 内 存 ， 映 射 为 树 和 结 点 模型 以 实现 解析 。 
“SAX 是 事件 驱动 的 流 解析 技术 ， 通 过 监听 注册 事件 ， 触 发 回调 方法 以 实现 解析 。 


“StAX 是 拉 式 流 解析 技术 ， 相 对 于 SAX 的 事件 驱动 推送 技术 ， 拉 式 解 析 使 得 读 取 过 程 可 以 主动 推进 当前 XMI 位 置 的 指针 而 不 是 被 动 获得 解析 中 的 XML 数 据 。 


对 应 的 ，JAXP 定 义 了 三 种 标准 类 型 的 输入 接口 Source (DOMSource、SAXSource、StreamSource) 和 输出 接口 Result (DOMResult、SAXResult、StreamResult) 。Jersey 可 以 使 用 JAXP 的 输入 类 
型 作为 REST 方 法 的 参数 ， 示 例 代 码 如 下 。 


@POST 

@Path ("stream") 

Q@Consumes (MediaType .APPLICATION XML) 
@Produces (MediaType .APPLICATION XML) 
public StreamSource getStreamSource ( 
javax.xml .transform.stream.StreamSource streamSource) { 


return streamSource; 


} 

Q@POST 

Q@Path ("sax") 

Q@Consumes (MediaType .APPLICATION XML) 
@Produces (MediaType .APPLICATION XML) 
// 


public SAXSource getSAXSource (javax.xml.transform.sax.SAXSource saxSource) { 


return saxSource; 


} 

Q@POST 

@Path ("dom") 

Q@Consumes (MediaType .APPLICATION XML) 
@Produces (MediaType .APPLICATION XML) 


wf 
关注 点 3 


支持 DOM 


技术 


public DOMSource getDOMSource (javax.xml.transform.dom.DOMSource domSource) { 


return domSource; 


} 

Q@POST 

@Path ("doc") 

@Consumes (MediaType .APPLICATION XML) 
@Produces (MediaType .APPLICATION XML) 


// 
关注 点 4 


支持 DOM 


技术 


public Document getDocument (org.w3c.dom.Document document) { 


} 


return document; 


在 这 段 代 码 中 ， 资 源 方法 getStreamSource() 使 


StAX 拉 式 流 解析 技术 支持 输入 /输出 类 型 为 StreamSource 的 请 求 ， 见 关注 点 1。getSAXSource() 方 法 使 


SAX 是 寻 


件 驱 动 的 流 解析 技术 支持 输入 /输出 


类 型 为 SAXSource 的 请 求 ， 见 关注 点 2。getDOMSource() 方 法 和 getDocument() 方 法 使 用 DOM 面 向 文档 解析 的 技术 支持 输入 /输出 类 型 分 别 为 DOMSource 和 Document 的 请 求 ， 见 关注 点 3 和 关注 点 4。 


2JAXB 标 准 


需要 指出 的 是 ， 从 理论 上 讲 ，JAXB 解 析 XML 的 性 能 不 如 JAXP， 但 使 用 JAXB 的 开发 效率 很 高 。 笔 者 所 在 的 开发 
因为 计算 机 执行 的 瓶 矣 在 IO， 而 无 论 使 
此 ， 如 果 连 XML 数据 都 趋 于 简 生 


的 观点 。 


Jersey 支 持 使 


AXB 通 过 序列 化 和 


AXP 的 缺点 是 需要 编码 解析 XML， 这 增加 了 开发 成 本 ， 但 对 业务 逻辑 的 实现 并 没有 实质 的 贡献 。JAXB 只 需要 在 POJO 中 定义 相关 的 注解 (早期 人 们 使 
schema 对 应 ， 无 须 对 XML 进 行程 序 式 解 析 ， 弥 补 了 JAXP 的 这 一 缺点 ， 


反 序列 化 实现 了 XML 类 
数据 反 序列 化 为 Java 对 象 。JAXB 的 注解 位 于 javax.xml.bind.annotation 包 中 ， 详 情 可 以 访问 JAXB 的 参考 实现 网 址 https://jaxbjj 


JAXB 作 为 XML 解析 的 技术 。 


加 


此 本 书 推荐 使 有 


居 和 POJO 对 象 的 自动 转换 过 程 。 在 运行 时 ，JAXB 通 过 编组 (marshall) 过 程 将 POJO 序 列 化 成 XML 格式 的 数据 ， 


ava.net/tutorial。 


团队 即使 有 


XML 配置 文件 来 做 这 件 事 ) ， 使 其 和 XML 的 


通过 解 编 (unmarshall) 过 程 将 XML 格式 的 


JAXB 解 析 XML， 从 实践 体会 而 言 ， 笔 者 并 不 支持 JAXB 影 响 系统 运行 性 全 


这 样 
因 


Q@POST 

@Path ("jaxb") 

Q@Consumes (MediaType .APPLICATION XML) 
@Produces (MediaType .APPLICATION XML) 
public Book getEntity (JAXBElement<Book> bookElement) { 


Book book = bookElement .getValue(); 
LOGGER. debug (book .getBookName () ); 
return book; 


} 
@POST 
@Consumes ({ MediaType.APPLICATION XML, MediaType.APPLICATION JSON }) 
@Produces (MediaType .APPLICATION XML) 
public Book getEntity (Book book) { 


} 


LOGGER. debug (book .getBookName () ); 
return book; 


六 ，JAXP 带 来 的 性 能 优势 就 可 以 基本 忽 


JAXBElement 作 为 REST 方 法 参数 的 形式 ， 也 支持 直接 使 用 POJO 作 为 REST 方 法 参数 的 形式 ， 后 一 种 更 为 常 


哪 种 技术 解析 ，XMI 数 据 本 身 是 一 样 的 ， 区 别 仅 在 于 解析 手段 。 而 REST 风 格 以 及 敏捷 思想 的 宗旨 就 是 简单 
阁 不 计 了 。 综合 考量 ， 实 现 起 来 更 简单 的 JAXB 更 适合 做 REST 开 发 。 


。 示 例 代码 如 下 。 


开发 过 程 简单 化 、 执 行 逻 辑 简单 化 ， 


以 上 JAXP 和 JAXB 的 测试 如 下 所 示 ， 其 传输 内 容 是 相同 的 ， 不 同 在 于 服务 器 端的 REST 方 法 定义 的 解析 类 型 和 返 


下 


> Content-Type: application/xml 


回 


值 类 型 。 


<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book bookId="100" bookName="TEST BOOK"/> 


2 
2 


< Content-Length: 79 
< Content-Type: text/html 


<?xml version="1.0" encoding="UTF-8"?><book bookId="100" bookName="TEST BOOK"/> 


从 测试 结果 可 以 看 到 ，POJO 类 的 字段 是 作为 XML 的 


[ 


属性 组 织 起 来 的 ， 详 见 如 下 的 图 书 实体 类 定义 。 


Q@XmlRootElement 
Public class Book implements Serializable { 


@XmlAttribute (name = "bookId") 
public Long getBookId() { 
return bookId; 


} 

@XmlAttribute (name = "bookName") 

public String getBookName () { 
return bookName; 

} 

@xmlAttribute (name = "publisher") 

public String getPublisher() { 
return publisher; 


} 


本 例 的 POJO 类 Book 的 字段 都 定义 为 XML 的 


(1) property 和 element 


属性 (property) 来 组 织 ，POJO 的 字段 也 可 以 作为 元 素 (element) 组 织 ， 见 关注 点 1。 如 何 定义 通常 取决 于 对 接 系统 的 设计 。 需 


本 


注意 的 是 ， 如 果 REST 请 


求 的 传输 数据 量 很 大 ， 并 且 无 须 和 外 系统 对 接 的 场景 ， 建 议 使 用 属性 来 组 织 XML， 这 样 可 以 极 大 地 减 小 XML 格式 的 数据 包 的 规模 。 


(2) XML _ SECURITY_DISABLE, 


Jersey 默 认 设置 了 XMLConstants.FEATURE_SECURE_PROCESSING (http://javax.xml.XMLConstants/feature/secure-processing) 属性 ， 当 属性 或 者 元 素 过 多 时 ， 会 报 “well-formedness 
error” 这 样 的 警告 信息 。 如 果 业 务 逻 辑 确 实 需要 设计 一 个 烦琐 的 POJO， 可 以 通过 设置 MessageProperties.XML_SECURITY_DISABLE 参 数值 为 TRUE 来 屏蔽 。 服 务 器 端 和 客户 端 示例 代码 如 下 。 


@Applicationpath ("/*") 
public class XXXResourceConfig extends ResourceConfig { 
public XXXResourceConfig() { 
Packages ("XXX.YYY.ZZZ") 7 
property (MessageProperties .XML SECURITY DISABLE, Boolean.TRUE); 
} 


} 
ClientConfig config = new ClientConfig(); 
config.property (MessageProperties.XML SECURITY DISABLE, Boolean.TRUE); 


3.3.6 JSON 类 型 


JSON 类 型 已 经 成 为 AJAX 技 术 中 数据 传输 的 实际 标准 。Jersey 提 供 了 4 种 处 理 JSON 数 据 的 媒体 包 。 表 3-6 展 示 了 4 种 技术 对 3 种 解析 流派 基于 POJO 的 JSON 绑 定 、 基 于 JAXB 的 JSON 绑 定 以 及 低级 的 ( 逐 
字 的 ) JSON 解 析 和 处 理 ] 的 支持 情况 。MOXy 和 Jackson 的 处 理 方式 相同 ， 它 们 都 不 支持 以 JSON 对 象 方式 解析 JSON 数 据 ， 而 是 以 绑 定 方式 解析 。Jettison 支 持 以 JSON 对 象 方式 解析 JSON 数 据 ， 同 时 支持 
JAXB 方 式 的 绑 定 。JSON-P 只 支持 JSON 对 象 方式 解析 这 种 方式 。 


表 3-6 Jersey 对 JSON 的 处 理 方式 列表 


JSON 
支持 包 MOXy JSON-P Jettison 


POJO-based JSON Binding 
JAXB-based JSON Binding Yes 


Low-level JSON parsing & processing 


下 面 将 介绍 MOXy、JSON-P、Jackson 和 Jettison 这 4 种 Jersey 支 持 的 JSON 处 理 技术 在 REST 式 的 Web 服 务 开发 中 的 使 用 情况 。 


1. 使 用 MOXy 处 理 JSON 


MOXy 是 EclipseLink 项 目的 一 个 模块 ， 其 官方 网 站 为 : http://www.eclipse.org/eclipselink/moxy.php， 宣 称 EclipseLink 的 MOXy 组 件 是 使 用 JAXB 和 SDO 作 为 XML 绑 定 的 技术 基础 。MOXy 实 现 了 JSR 
222 标 准 (JAXB 2.2) 和 JSR 235 标 准 (SDO 2.1.1) ， 这 使 得 使 用 MOXy 的 Java 开 发 者 能 够 高 效 地 完成 Java 类 和 XML 的 绑 定 ， 所 要 花费 时 间 的 只 是 使 用 注解 来 定义 它们 之 间 的 对 应 关系 。 同 时 ，MOXy 实 现 
了 JSR 353 标 准 (Java API for Processing JSON 1.0) ， 以 JAXB 为 基础 ， 来 实现 对 JSR 353 的 支持 。 下 面 开始 讲述 使 用 MOXy 实 现在 REST 应 用 中 解析 JSON 的 完整 过 程 。 


全 阅读 指南 本 小 节 示 例 所 在 目录 是 : jax-rs2-guide\sample\3\1simple-service-moxy。 
源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/1simple-service-moxy 


(1) 定义 依赖 


MOXy 是 Jersey 默 认 的 JSON 解 析 方 式 ， 可 以 在 项 目 中 添加 MOXy 的 依赖 包 来 使 用 MOXy。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-moxy</artifactId> 
</dependency> 


(2) 定义 Application 


如 果 使 用 Servlet 3， 则 可 以 不 定义 web.xml 配 置 ， 否 则 需 参 考 2.3 节 的 讲述 。 


MOXy 的 Feature 接 口 实 现 类 是 MoxyJsonFeatureClientProperties.MOXY_JSON_FEATURE_DISABLE， 客 户 端 禁 


@ApplicationPath ("/api/*") 
public class JsonResourceConfig extends ResourceConfig { 
public JsonResourceConfig() { 
register (BookResource.class); 
/* 
property( 
org.glassfish.jersey.CommonProperties.MOXY JSON FEATURE DISABLE, true); 
四 
/ 


(3) 定义 资源 类 


接 下 来 ， 我 们 定义 一 个 图 书 资源 类 BookResource， 并 在 : 


中 实现 表述 媒体 类 型 为 JSON 的 资源 方法 getBooks()。 支 持 JSON 格 式 的 表述 的 资源 类 定义 如 下 。 


@Path ("books") 
// 
关注 点 1 


: @Produces 
注解 和 @Consumes 
注解 上 移 到 接口 
@Consumes (MediaType .APPLICATION JSON) 
@Produces (MediaType .APPLICATION JSON) 
public class BookResource { 
Private static final Logger LOGGER = Logger.getLogger (BookResource.class); 
private static final HashMap<Long, Book> memoryBase; 
static { 
memoryBase = com.google.common.collect .Maps.newHashMap (); 
memoryBase.put (lL, new Book(lL, "Java Restful Web Services 
使 用 指南 ") ) ; 
memoryBase.put (2L, new Book(2L, "Java EE 7 
精髓 ") ) ; 


} 
@GET 


类 方法 无 须 再 定义 QProduces 
注解 和 @Consumes 
注解 
public Books getBooks () { 
final List<Book> bookList = new ArrayList<>(); 
final Set<Map.Entry<Long, Book>> entries = BookResource.memoryBase.entrySet (); 
final Iterator<Entry<Long, Book>> iterator = entries.iterator(); 
while (iterator.hasNext()) { 
final Entry<Long, Book> cursor = iterator.next (); 
BookResource .LOGGER.debug (cursor.getKey ()); 
bookList.add (cursor.getValue()); 
} 
final Books books = new Books (bookList); 
BookResource .LOGGER. debug (books); 
return books; 


支持 的 所 有 资源 方法 


在 这 段 代 码 中 ， 需 要 注意 的 是 ， 资 源 类 BookResource 上 定义 了 @Consumes (MediaType.APPLICATION JSON) 和 @Produces (MediaType.APPLICATION JSON)， 代表 
都 使 用 MediaType.APPLICATION_JSON 类 型 作为 请 求 和 响应 的 数据 类 型 ， 见 关注 点 1。 因 此 ，getBooks() 方 法 上 无 须 再 定义 @Consumes 和 @Produces， 见 关注 点 2。 


(4) 单元 测试 


JSON 处 理 的 单元 测试 主要 关注 请 求 的 响应 中 JSON 数 据 的 可 用 性 、 完 整 性 和 一 致 性 。 在 本 章 使 用 的 单元 测试 中 ， 验 证 JSON 处 理 无 误 的 标准 是 测试 的 返回 值 是 一 个 Java 类 型 的 实体 类 实例 ， 整 个 请 求 处 
理 过 程 中 没有 异常 发 生 。 测 试 代码 如 下 。 


public class JsonTest extends JerseyTest { 
private final static Logger LOGGER = Logger.getLogger (JsonTest .class) 7 
Override 
protected Application configure () { 
enable (TestProperties.LOG TRAFFIC); 
enable (TestProperties .DUMP ENTITY); 
return new ResourceConfig (BookResource.class); 
} 
Q@Test 
Public void testGettingBooks () { 
J 
关注 点 1 
: 在 请 求 中 定义 媒体 类 型 为 JSON 
Books books = target ("books") .request (MediaType.APPLICATION JSON_TYPE) . 
get (Books .class) 7 
for (Book book : books .getBookList()) { 
LOGGER. debug (book.getBookName () ) 
} 


在 这 段 代 码 中 ， 测 试 方法 testGettingBooks() 定 义 了 请 求 资源 的 数据 类 型 为 MediaType.APPLICATION_JSON_TYPE 来 匹配 服务 器 端 提 供 的 REST AP1， 其 作用 是 定义 请 求 的 媒体 类 型 为 JSON 格 式 ， 见 关 
注 点 1。 


(5) 集成 测试 


除了 单元 测试 ， 我 们 使 用 cURL 来 做 集成 测试 。 启 动 本 示例 ， 输 入 如 下 所 示 的 命令 ， 将 返 


回 


JSON 格 式 的 数据 。 


curl http://localhost:8080/simple-service-moxy/api/books 
curl -H "Content-Type: application/json" http://localhost:8080/simple-service-moxy/api/books 


{"bookList":{"book": [{"bookId":1,"bookName":"Java Restful Web Services 
使 用 指南 "]} ， 

{"bookId":2,"bookName":"Java EE 7 

精髓 "}] }} 


2. 使 用 JSON-P 处 理 JSON 


JSON-P 的 全 称 是 处 理 API) ， 而 不 是 JSON with Padding (JSONP) ， 两 者 只 是 名 称 相仿 ， 用 途 却 大 不 相同 。JSON-P 是 JSR 353 标 准 规范 ， 用 于 统一 Java 处 理 JSON 格 式 数据 的 AP1， 其 生产 和 消费 的 
SON 数 据 以 流 的 形式 ， 类 似 StAX 处 理 XML， 并 为 JSJON 数 据 建 立 Java 对 象 模型 ， 类 似 DOM。 而 JSONP 是 用 于 异步 请 求 中 传递 脚本 的 回调 函数 来 解决 跨 域 问题 的 。 下 面 开 始 讲述 使 用 SON-P 实 现在 REST 应 
中 解析 JSON 的 完整 过 程 。 


回 


对 


人 阅读 指南 “本 小 节 示例 所 在 目录 是 : 


jax-rs2-guide\sample\3\4simple-service-jsonp 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/4simple-service-jsonp 


(1) 定义 依赖 


使 用 JSON-P 方 式 处 理 JSON 类 型 的 数据 ， 需 要 在 项 目的 Maven 配 置 中 声明 如 下 依赖 。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-processing</artifactId> 
</dependency> 


(2) 定义 Application 


使 用 JSON-P 的 应 用 ， 上 默认 不 需要 在 其 application 中 注册 JsonProcessingFeature， 除 非 使 用 了 如 下 设置 ， 分 别 上 
去 活 JSON-P 功 能 : 


于 在 服务 器 和 客户 端 两 侧 去 活 JSON-P 功 能 、 在 服务 器 端 去 活 JSON-P 功 能 、 在 客户 端 


* CommonProperties.JSON_PROCESSING_FEATURE_DISABLE 
* ServerProperties.JSON_PROCESSING_FEATURE_DISABLE 


* ClientPropetties.JSON_PROCESSING _FEATURE_DISABLE 


JsonGenerator.PRETTY_PRINTING 属 性 用 于 格式 化 JSON 数 据 的 输出 ， 当 属性 值 为 TRUE 时 ，MessageBodyReader<T> 和 MessageBodyWriter<T> 实 例会 对 JSON 数 据 进行 额外 处 理 ， 使 得 JSON 数 据 
可 以 格式 化 打印 。 该 属性 的 设置 在 application 中 ， 示 例 代码 如 下 ， 见 关注 点 1。 


@ApplicationPath ("/api/*") 
public class JsonResourceConfig extends ResourceConfig { 
public JsonResourceConfig() { 
register (BookResource.class); 


关注 点 1 
: 配置 JSON 
格式 化 输出 
Property (JsonGenerator .PRETTY PRINTING, true); 
} 


(3) 定义 资源 类 


资源 类 BookResource 同 上 例 一 样 定义 了 类 级 别 的 @Consumes 和 @Produces， 媒 体格 式 为 MediaType.APPLICATION_JSON。 资 源 类 BookResource 的 示例 代码 如 下 。 


Q@Path ("books") 
@Consumes (MediaType .APPLICATION JSON) 
@Produces (MediaType .APPLICATION JSON) 
public class BookResource { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
static { 
memoryBase = com.google.common.collect .Maps.newHashMap (); 


关注 点 1 
: 构建 JsonobjectBuilder 
实例 


JsonObjectBuilder jsonObjectBuilder = Json.createObjectBuilder (); 


// 
点 2 
建 JsonObject 


JsonObject newBookl = jsonObjectBuilder.add ("bookId", 1). 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


@GET 

public JsonArray getBooks() { 
// 

JsonArrayBuilder 


final JsonArrayBuilder arrayBuilder = Json.createArrayBuilder (); 
final Set<Map.Entry<Long, JsonObject>> entries = 
BookResource.memoryBase.entrySet (); 
final Iterator<Entry<Long, JsonObject>> iterator = entries.iterator(); 
while (iterator.hasNext()) { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/O0EBPS/Text/... 


} 
// 
关注 点 4 
: 构建 JsonArray 
实例 
JsonArray result = arrayBuilder.build(); 
return result; 


在 这 段 代 码 中 ，JsonObjectBuilder 用 于 构造 JSON 对 象 ， 见 关注 点 1; JsonObject 是 JSON-P 定 义 的 JSON 对 象 类 ， 见 关注 点 2; JsonArrayBuilder 用 于 构造 JSON 数 组 对 象 ， 见 关注 点 3; JsonArray 是 
JSON 数 组 类 ， 见 关注 点 4。 


(4) 单元 测试 


JSON-P 示 例 的 单元 测试 需要 关注 JSJON-P 定 义 的 JSON 类 型 ， 测 试验 收 标准 在 前 一 小 节 MOXy 的 单元 测试 中 已 经 讲述 ， 示 例 代 码 如 下 。 


public class JsonTest extends JerseyTest { 
private final static Logger LOGGER = Logger.getLogger (JsonTest .class) 7 
QOverrigde 
protected Application configure() { 
enable (TestProperties.LOG TRAFFIC); 
enable (TestProperties.DUMP ENTITY); 
return new ResourceConfig (BookResource.class); 
} 
Q@Test 
public void testGettingBooks () { 
a 


1 

求 的 响应 类 型 为 JsonArray 
JsonArray books = target ("books") .request (MediaType.APPLICATION JSON_TYPE) . 
get (JsonArray.class); 
for (JsonValue jsonValue : books) { 


dh 


关注 点 2 

: 强制 转换 JsonValue 

为 JsonObject 
JsonObject book = (JsonObject) jsonValue; 
LOGGER. debug (book.getString ("bookName"));// 


关注 点 3 
: 打印 输出 测试 结果 
} 
} 


在 这 段 代码 片 段 中 ，JsonArray 是 getBooks() 方 法 的 返回 类 型 ，get 请 求 发 出 后 ， 对 应 的 方法 是 getBooks() 方 法 ， 见 关注 点 1。JsonValue 类 型 是 一 种 抽象 化 的 JSON 数 据 类 型 ， 此 处 类 型 强制 转化 为 
JsonObject， 见 关注 点 2。getString() 方 法 是 将 JsonObject 对 象 的 某 个 字段 以 字符 串 类 型 返回 ， 见 关注 点 3。 


回 


(5) 集成 测试 


使 用 cURL 对 本 示例 进行 集成 测试 的 结果 如 下 所 示 。JSON 数 据 结果 可 以 格式 化 打印 输出 。 


curl http://localhost:8080/simple-service-jsonp/api/books 


{ 
"bookId":1, 
"bookName":"JSF 
Richfaces 
使 用 指南 "， 
"publisher™":" 
电子 " 
博文 " 
] 
{ 
"bookId":2, 
"bookName":"Java Restful Web Services 
使 用 指南 "， 
"publisher":" 
机 工 " 
华章 " 
} 


curl http://localhost:8080/simple-service-jsonp/api/books/book?id=2 


{ 
"bookId":2, 


"bookName":"Java Restful Web Services 
使 用 指南 "， 

"publisher":" 
机 工 
华章 " 
} 
curl -H "Content-Type: application/json" -X POST 
-d "{\"bookName\":\"abc\", \"publisher\":\"me\"}" 
http://localhost:8080/simple-service-jsonp/api/books 
{ 

"bookId":12447994371104, 

"bookName" : "abc", 

"publisher": "me" 


3. 使 用 Jackson 处 理 JSON 


Jackson 是 一 种 目前 比较 流行 的 JSON 支 持 技术 ， 其 源 代码 托管 于 GitHub， 地 址 是 : https://github.com/FasterXML/jackson。Jackson 提 供 了 3 种 JSON 解 析 方 式 。 


: 第 一 种 是 基于 流 式 API 的 增 量 式 解析 /生成 JSON 的 方式 ， 读 写 JSON 内 容 的 过 程 是 通过 离散 事件 触发 的 ， 其 底层 基于 StAX API 读 取 JSON 使 用 org.codehaus.jackson.JsonParser， 写 入 JSON 使 用 


org.codehaus.jackson.JsonGenerator。 
“ 第 二 种 是 基于 树 形 结构 的 内 存 模 型 ， 提 供 一 种 不 变 式 的 JsonNode 内 存 树 模型 ， 类 似 DOM 树 。 


“ 第 三 种 是 基于 数据 绑 定 的 方式 ，org.codehaus.jackson.map.ObjectMapper 解 析 ， 使 用 JAXB 的 注解 。 


下 面 开 始 讲述 使 用 Jackson 实 现在 REST 应 用 中 解析 JSON 的 完整 过 程 。 


全 阅读 指南 “本 小 节 示 例 所 在 目录 是 : 


jax-rs2-guide\sample\3\2simple-service-jackson 


源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/2simple-service-jackson 


(1) 定义 依赖 


使 用 Jackson 方 式 处 理 JSON 类 型 的 数据 ， 需 要 在 项 目的 Maven 配 置 中 声明 如 下 依赖 。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-jackson</artifactId> 
</dependency> 


(2) 定义 Application 


使 用 Jackson 的 应 用 ， 需 要 在 其 application 中 注册 JacksonFeature。 同 时 ， 如 果 有 必要 根据 不 同 的 实体 类 做 详细 的 解析 ， 则 可 以 注册 ContextResolver 的 实现 类 ， 示 例 代 码 如 下 。 


@ApplicationPath ("/api/*") 
public class JsonResourceConfig extends ResourceConfig { 
public JsonResourceConfig() { 
register (BookResource.class); 
register (JacksonFeature.class); 
a 
关注 点 1 
: 注册 ContextResolver 
的 实现 类 JsonContextProvider 
register (JsonContextProvider.class); 


} 


在 这 段 代 码 中 ， 注 册 了 ContextResolver 的 实现 类 JsonContextProvider， 用 于 提供 JSON 数 据 的 上 下 文 ， 见 关注 点 1。 有 关 ContextResolver 的 详细 信息 ， 可 参考 4.2 节 。 
(3) 定义 POJO 


本 例 定义 了 3 种 不 同方 式 的 POJO， 以 演示 Jackson 处 理 JSON 的 多 种 方式 ， 分 别 是 JsonBook、JsonHybridBook 和 JsonNoJaxbBook。 


第 一 种 方式 是 仅 用 JAXB 注 解 的 普通 的 POJO， 示 例 类 JsonBook 如 下 。 


@XmlRootElement 
@xmlType (propOrder = {"bookId", "bookName", "chapters"}) 
public class JsonBook { 
private String[] chapters; 
private String bookId; 
private String bookName; 
public JsonBook() { 
bookId = "1"; 
bookName = "Java Restful Web Services 
使 用 指南 "; 


chapters = new String[0]; 
} 


public String getBookId() { 
return bookId; 


} 
public void setBookId (String bookId) { 
this.bookId = bookId; 


} 

public String getBookName () { 
return bookName; 

: 

Public void setBookName (String bookName) { 
this.bookName = bookName; 


} 

public String[] getChapters() { 
return chapters; 

} 

public void setChapters (String[] chapters) { 
this.chapters = chapters; 

} 


第 二 种 方式 是 将 JAXB 的 注解 和 Jackson 提 供 的 注解 混合 使 用 的 POJO， 示 例 类 JsonHybridBook 如 下 。 


@XmlRootElement // 
关注 点 1 
: 使 用 JAXB 


注解 
public class JsonHybridBook { 


@JsonProperty ("bookId") 
private String bookId; 
@JsonProperty ("bookName") 
private String bookName; 
public JsonHybridBook() { 
bookId = "2"; 


bookName "Java Restful Web Services 


使 用 指南 "; 
} 
} 


在 这 段 代 码 中 ， 分 别 使 用 了 JAXB 的 注解 javax.xml.bind.annotation.XmlRootElement， 见 关注 点 1， 以 及 Jackson 的 注解 org.codehausjackson.annotate.JsonProperty， 见 关注 点 2， 分 别 定义 XML 
根 元 素 和 XML 属性 。 


第 三 种 方式 是 不 使 用 任何 注解 的 POJO， 示 例 类 JsonNoJaxbBook 如 下 。 


public class JsonNoJaxbBook { 
private String[] chapters; 
private String bookId; 
private String bookName; 
public JsonNoJaxbBook() { 
bookId = 
bookName 
使 用 指南 "; 


chapters = new String[0]; 


Java Restful Web Services 


} 

public String[] getChapters() { 
return chapters; 

} 

public void setChapters (String[] chapters) { 
this.chapters = chapters; 

} 

public String getBookId() { 
return bookId; 

} 

public void setBookId (String bookId) { 
this.bookId = bookId; 


} 

public String getBookName () { 
return bookName; 

} 

public void setBookName (String bookName) { 
this.bookName = bookName; 


} 


这 样 的 三 种 POJO 如 何 使 用 Jackson 来 处 理 呢 ? 我 们 继续 往 下 看 。 


(4) 定义 资源 类 


资源 类 BookResource 用 于 演示 Jackson 对 上 述 三 种 不 同 POJO 的 支持 ， 示 例 代码 如 下 。 


@Path ("books") 
@Consumes (MediaType .APPLICATION JSON) 
@Produces (MediaType .APPLICATION JSON) 
public class BookResource { 

@Path ("/emptybook") 

Q@GET 


: 支持 第 一 种 方式 的 POJO 
美 型 

public JsonBook getEmptyArrayBook() { 
return new JsonBook(); 


@Path ("/hybirdbook") 
@GET 
// 


关注 点 2 
: 支持 第 二 种 方式 的 POJO 


public JsonHybridBook getHybirdBook() { 
return new JsonHybridBook(); 

} 

@Path ("/nojaxbbook") 

@GET 


public JsonNoJaxbBook getNoJaxbBook() { 
return new JsonNoJaxbBook (); 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代码 中 ， 资 源 类 BookResource 定 义 了 路 径 不 同 的 3 个 GET 方 法 ， 返 回 类 型 分 别 对 应 上 述 的 3 种 POJO， 见 关注 点 1~ 关 注 点 3。 有 了 这 样 的 资源 类 ， 我 们 就 可 以 向 其 发 送 GET 请 求 ， 并 获取 不 同类 型 
的 JSON 数 据 ， 以 研究 Jackson 是 如 何 支 持 这 3 种 POJO 的 JSON 转 换 。 


(5) 上 下 文 解析 实现 类 


JsonContextProvider 是 ContextResolver (上 下 文 解析 器 ) 的 实现 类 ， 
种 解析 方式 的 示例 代码 如 下 。 


作用 是 根据 上 下 文 提供 的 POJO 类 型 ， 分 别提 供 两 种 解析 方式 。 第 一 种 是 默认 的 方式 ， 第 二 种 是 混合 使 用 Jackson 和 JAXB。 两 


Q@Provider 
public class JsonContextProvider implements ContextResolver<ObjectMapper> { 
final ObjectMapper d; 
final ObjectMapper c; 
public JsonContextProvider() { 
// 


关注 点 1 

: 实例 化 ObjectMapper 
d = createDefaultMapper () 7 
c= createCombinedMapper (); 


} 

private static ObjectMapper createCombinedMapper() { 
Pair ps = createIntrospector (); 
ObjectMapper result = new ObjectMapper (); 
result.setDeserializationConfig( 
result .getDeserializationConfig() .withAnnotationIntrospector (ps)); 
result .setSerializationConfig( 
result .getSerializationConfig() .withAnnotationIntrospector (ps)); 
return result; 


private static ObjectMapper createDefaultMapper () 
ObjectMapper result = new ObjectMapper (); 
result .configure (Feature.INDENT OUTPUT, true); 
return result; 


3 


} 

private static Pair createIntrospector() 
AnnotationIintrospector p 
AnnotationIintrospector s 
return new Pair(p, s); 


{ 
new JacksonAnnotationIntrospector(); 
new JaxbAnnotationIntrospector (); 


} 
QOverride 


a 
关注 点 2 
: 判断 POJO 
类 型 返回 相应 的 ObjectMapper 
实例 


public ObjectMapper getContext (Class<?> type) { 


if (type == JsonHybridBook.class) 
return cc; 

} else { 
return dy 


{ 


} 


在 这 段 代 码 中 ，JsonContextProvider 定 义 并 实例 化 了 两 种 类 型 ObjectMapper， 见 关注 点 1， 在 实现 接 
点 2。 通 过 这 样 的 实现 ， 当 流程 获取 JSON 上 下 文 时 ， 即 可 使 用 Jackson 依 赖 包 完成 对 相关 POJO 的 处 理 。 


方法 getCo 


(6) 单元 测试 


测试 类 BookResourceTest 的 目的 是 对 支持 上 述 三 种 POJO 的 资源 地 址 发 起 请 求 并 测 斌 结果， 示例 代码 如 下 。 


public class BookResourceTest extends JerseyTest { 
private static final Logger LOGGER = Logger.getLogger (BookResourceTest.class); 
WebTarget booksTarget = target ("books"); 
QOverride 
protected ResourceConfig configure () 


// 


关注 点 1 
: 服务 器 端 配置 
enable (TestProperties.LOG TRAFFIC); 
enable (TestProperties.DUMP ENTITY); 
ResourceConfig resourceConfig = new ResourceConfig (BookResource.class); 
// 
: 注 点 2 
: 注册 JacksonFeature 
resourceConfig.register (JacksonFeature.class); 
return resourceConfig; 


{ 


QOverride 


protected void configureClient (ClientConfig config) { 
// 


册 JacksonFeature 
config.register (new JacksonFeature()); 
config.register (JsonContextProvider.class); 


类 型 的 资源 方法 
public void testEmptyArray() 
JsonBook book = booksTarget .path ("emptybook") .request (MediaType.APPLICATION JSON) . 
get (JsonBook.class); 
LOGGER. debug (book); 


{ 


} 
Q@Test 
// 


式 出 参 为 JsonHybridBook 

的 资源 方法 

public void testHybrid() { 

JsonHybridBook book = booksTarget .path ("hybirdbook"). 
request (MediaType .APPLICATION JSON) . 

get (JsonHybridBook.class); 加 

LOGGER. debug (book) ; 


} 

Q@Test 

es 

i6 

: 测试 出 参 为 JsonNoJaxbBook 

类 型 的 资源 方法 

public void testNoJaxb() { 
JsonNoJaxbBook book = booksTarget .path ("nojaxbbook"). 
request (MediaType.APPLICATION JSON) . 
get (JsonNoJaxbBook.class); 
LOGGER. debug (book); 


ntext(0 中 ， 通 过 判断 当前 POJO 的 类 型 ， 返 回 两 种 ObjectMapper 实 例 之 一 ， 见 关注 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代码 中 ， 首 先 要 在 服务 器 端 注 册 支 持 Jackson 功 能 ， 见 关注 点 2， 同 时 在 客户 端 也 要 注册 支持 Jackson 功 能 并 注 | 


骨 JsonContextProvider， 见 关注 点 3。 该 测试 类 包含 了 


于 测试 3 种 类 


了 POJO 的 测 


试用 例 ， 见 关注 点 4~ 关 注 点 6。 注 意 ，configure() 方 法 是 覆盖 测试 服务 器 实例 行为 ，configureClient() 方 法 是 覆盖 测试 客 
(7) 集成 测试 
使 用 cURL 对 本 例 进行 集成 测试 ， 结 果 如 下 所 示 。 


端 实例 行为 ， 见 关注 点 1。 


curl http://localhost:8080/simple-service-jackson/api/books 
{ 

"bookList" : 
"bookId 
"bookName" 

使 用 指南 "， 
"publisher" 

{ 
"bookId" : 
"bookName 
精髓 "， 
"publisher™ : 
] 


"Java Restful Web Services 


: NOLL 


}, 


} 
} 
curl http://localhost:8080/simple-service-jackson/api/books/emptybook 


[ 


"chapters" 下 
"bookId" : 
"bookName" 


使 用 指南 " 
} 


’ 
"Java Restful Web Services 


curl http://localhost:8080/simple-service-jackson/api/books/hybirdbook 
{"bookId":"2", "bookName":"Java Restful Web Services 

使 用 指南 "} 

curl http://localhost:8080/simple-service-jackson/api/books/nojaxbbook 
{ 


], 


"chapters" : 
"bookId" 


"bookName" : "Java Restful Web Services 


使 用 指南 " 
i 


4. 使 用 Jettison 处 理 JSON 


Jettison 是 一 种 使 用 StAX 来 解析 JSON 的 实现 。 项 目地 址 是 : http://jettison.codehaus.org。jJettison 项 目 起 初 用 于 为 CXF 提 供 基于 JSON 的 Web 服 务 ， 在 XStream 的 Java 对 象 的 序列 化 中 也 使 用 了 
Jettison。Jettison 支 持 两 种 JSON 了 映射 到 XML 的 方式 。Jersey 默 认 使 用 Mapped 方 式 ， 另 一 种 叫做 BadgerFish。 


下 面 开 始 讲述 使 用 Jettison 实 现在 REST 应 用 中 解析 JSON 的 完整 过 程 。 


人 阅读 指南 “本 小 节 示例 所 在 目录 是 : 


jax-rs2-guide\sample\3\3simple-service-jettison 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/3simple-service-jettison 


(1) 定义 依赖 


使 用 Jettison 方 式 处 理 JSON 类 型 的 数据 ， 需 要 在 项 目的 Maven 配 置 中 声明 如 下 依赖 。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-json-jettison</artifactId> 
</dependency> 


(2) 定义 Application 


使 用 Jettison 的 应 用 ， 需 要 在 其 application 中 注册 JettisonFeature。 同 时 ， 如 果 有 必要 根据 不 同 的 实体 类 做 详细 的 解析 ， 那 么 可 以 注册 ContextResolver 的 实现 类 ， 示 例 代 码 如 下 。 


@ApplicationPath ("/api/*") 
public class JsonResourceConfig extends ResourceConfig { 
public JsonResourceConfig() { 
register (BookResource.class); 


关注 点 1 

: 注册 JettisonFeature 

和 ContextResolver 

的 实现 类 JsonContextResolver 
register (JettisonFeature.class); 
register (JsonContextResolver.class); 


在 这 段 代 码 中 ， 注 册 了 Jettison 功 能 JettisonFeature 和 ContextResolver 的 实现 类 JsonContext Resolver， 以 便 使 用 Jettison 处 理 JSON， 见 关注 点 1。 


(3) 定义 POJO 


本 例 定 义 了 两 个 类 名 不 同 但 内 容 相 同 的 POJO (JsonBook 和 JsonBook2) ， 用 以 演示 Jettison 对 JSON 数 据 以 JETTISON_MAPPED (default notation) 和 BADGERFISH 两 种 不 同方 式 处 理 的 情况 。 


Q@XxmlRootElement 
public class JsonBook { 
private String bookId; 
Private String bookName; 
public JsonBook() { 
bookId = "1"; 
bookName = "Java Restful Web Services 


使 用 指南 "; 
} 


@XmlElement 
public String getBookId() { 
return bookId; 
} 
public void setBookId 
(String bookId 
) { 
this.bookId = bookId; 


} 
@xmlElement 
public String getBookName () { 
return bookName; 
} 
public void setBookName 
(String bookName 
4 
this.bookName = bookName; 


(4) 定义 资源 类 


资源 类 BookResource 为 两 种 JSON 方 式 提供 了 资源 地 址 ， 示 例 代码 如 下 。 


@Path ("books") 
public class BookResource { 
private static final Logger LOGGER = Logger.getLogger (BookResource.class); 
private static final HashMap<Long, Book> memoryBase; 
static { 
memoryBase = com.google.common.collect .Maps.newHashMap (); 
memoryBase.put (lL, new Book(lL, "Java Restful Web Services 
使 用 指南 "”) ) ; 
memoryBase.put (2L, new Book(2L, "Java EE 7 
精髓 ") ) 7 


} 
@Path ("/jsonbook") 
@GET 
// 
关注 点 1 
: 返回 类 型 为 JsonBook 
的 GET 
方法 
Public JsonBook getBook() { 
final JsonBook book = new JsonBook(); 
BookResource .LOGGER. debug (book); 
return book; 


E 

@Path ("/jsonbook2") 
@GET 

好 


关注 点 2 

: 返回 类 型 为 JsonBook2 
的 GET 

方法 


Public JsonBook2 getBook2 () { 
final JsonBook2 book = new JsonBook2 () 7 
BookResource .LOGGER. debug (book); 
return book; 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


} 


在 这 段 代码 中 ， 资 源 类 BookResource 定 义 了 路 径 不 同 的 两 个 GET 方 法 ， 返 回 类 型 分 别 是 JsonBook 和 JsonBook2， 分 别 见 关 注 点 1 和 关注 点 2。 有 了 这 样 的 资源 类 ， 我 们 就 可 以 向 


取 不 同类 型 的 JSON 数 据 ， 以 研究 Jettison 是 如 何 处 理 JETTISON_MAPPED 和 BADGERFISH 两 种 不 同 格式 的 JSON 数 据 的 。 


(5) 上 下 文 解析 实现 类 


JsonContextResolver 实 现 了 ContextResolver 接 口 ， 示 例 代 码 如 下 。 


发 送 GET 请 求 ， 并 获 


Q@Provider 
public class JsonContextResolver implements ContextResolver<JAXBContext> { 
Private final JAXBContext Context17 
private final JAXBContext context2; 
@SuppressWarnings ("rawtypes") 
public JsonContextResolver() throws Exception { 


Class[] clz = new Class[] {JsonBook.class, JsonBook2.class, Books.class, Book.class}; 


好 
关注 点 1 
: 实例 化 JettisonJaxbContext 
this .context1 new JettisonJaxbContext (JettisonConfig.DEFAULT, clz); 
this.context2 


} 
QOverride 
public JAXBContext getContext (Class<?> objectType) { 


// 
关注 点 2 
: 判断 POJO 
型 返回 相应 的 JAXBContext 
实例 


if (objectType == JsonBook2.class) { 
return context2; 

} else { 
return context17 


} 


new JettisonJaxbContext (JettisonConfig.badgerFish() .build(), clz); 


在 这 段 代 码 中 ，JsonContextResolver 定 义 了 两 种 JAXBContext， 分 别 使 用 Mapped 方 式 和 BadgerFish 方 式 ， 见 关注 点 1。 这 两 种 方式 的 参数 信息 来 自 Jettison 依 赖 包 的 JettisonConfig 类 。 在 实现 接 
方法 getContext(0 中 ， 根 据 不 同 的 POJO 类 型 ， 返 回 两 种 JAXBContext 实例 之 一 ， 见 关注 点 2。 通 过 这 样 的 实现 ， 


(6) 单元 测试 


单元 测试 类 BookResourceTest 的 目的 是 对 支持 上 述 两 种 JSON 方 式 的 资源 地 址 发 起 请 求 并 测试 结果 ， 示 例 代码 如 下 。 


程 获取 JSON 上 下 文 时 ， 即 可 使 用 Jettison 依 赖 包 完成 对 相关 POJO 的 处 理 。 


public class BookResourceTest extends JerseyTest { 
private static final Logger LOGGER = Logger.getLogger (BookResourceTest.class); 
QOverrigde 
protected ResourceConfig configure() { 
enable (TestProperties.LOG TRAFFIC) 
enable (TestProperties.DUMP ENTITY) 
ResourceConfig resourceConfig = ne 


// 


W ResourceConfig (BookResource.class); 


关注 点 1 

: 注册 JettisonFeature 

和 JsonContextResolver 
resourceConfig.register (JettisonFeature.class); 
resourceConfig.register (JsonContextResolver.class); 
return resourceConfig; 


} 
QOverride 
protected void configureClient (ClientConfig config) { 
// 
关注 点 2 
: 注册 JettisonFeature 
和 JsonContextResolver 
config.register (new JettisonFeature () ) .register (JsonContextResolver.class); 


QTest 
public void testJsonBook () { 
// 


JsonBook book = target ("books") .path ("jsonbook"). 
request (MediaType .APPLICATION JSON) . 

get (JsonBook.class); 

LOGGER. debug (book); 
//{"jsonBook":{"bookId":1,"bookName":"abc"}} 


Q@Test 
public void testJsonBook2 () { 
2 


4 
: 测试 返回 类 型 为 JsonBook2 
的 GET 
方法 


JsonBook2 book = target ("books") .path ("jsonbook2"). 

request (MediaType .APPLICATION JSON) . 

get (JsonBook2.class); 

LOGGER. debug (book); 

//{"jsonBook2": {"bookId": {"$":"1"}, "bookName": {"$":"abc"}}} 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代 码 中 ， 首 先 要 在 服务 器 和 客户 端 两 侧 注册 Jettison 功 能 和 JsonContextResolver， 见 关注 点 1 和 关注 点 2。 


(7) 集成 测试 


该 测试 类 包含 了 


使 用 CURL 对 本 例 进行 集成 测试 ， 结 果 如 下 所 示 。 可 以 看 到 Mapped 和 BadgerFish 两 种 方式 的 JSON 数 据 内 容 不 同 。 


curl http://localhost:8080/simple-service-jettison/api/books 
{"books":{"bookList":{"book": [{"@bookId":"1","@bookName":"Java Restful Web 
Services 

使 用 指南 "}, {"@bookId":"2", "@bookName":"Java EE 7 

精髓 "}] }}} 

Jettison mapped notation 

curl http://localhost:8080/simple-service-jettison/api/books/jsonbook 


测试 两 种 格式 JSON 数 据 的 测试 


例 ， 见 关注 点 3 和 4。 


{"jsonBook": {"bookId":1, "bookName":"Uava Restful Web Services 

使 用 指南 "}} 

Badgerfish notation 

curl http://localhost:8080/simple-service-jettison/api/books/jsonbook2 
{"jsonBook2": {"bookId":{"$":"1"},"bookName":{"$":"Java Restful Web Services 
使 用 指南 "}}} 


最 后 简要 介绍 一 下 Atom 类 型 。 


Atom 是 一 种 基于 XML 的 文档 格式 ， 该 格式 的 标准 定义 在 IETF RFC 4287 (Atom Syndication Format， 即 Atom 联 合格 式 ) ， 其 推出 的 目的 是 用 来 蔡 换 RSS。AtomPub 是 基于 Atom 的 发 布 协议 ， 定 义 
在 IETF RFC 5023 (Atom Publishing Protocol) 。 


Jersey 2 没有 直接 引入 支持 Atom 格 式 的 媒体 包 ， 但 Jersey 1.x 中 包含 jersey-atom 包 。 这 说 明 jJersey 的 基本 架构 对 支持 基于 XML 类 型 的 数据 并 不 是 问题 ， 这 种 可 播 拔 的 媒体 包 支 持 对 于 Jersey 本 身 更 具 灵 
活性 ， 对 使 用 Jersey 的 REST 服 务 更 具 可 扩展 性 。 


3.4 “REST 连 通 性 


REST 的 一 个 重要 的 特性 就 是 连通 性 。Web Link 和 HATEOAS 以 不 同方 式 实现 了 REST 式 服务 的 连通 性 。 


.Web Link 定 义 在 IETF RFC 5988 (Web Linking) ， 是 通过 在 HTTP 头 中 定义 链接 信息 ， 以 描述 当前 页 面 与 链接 页 面 之 间 的 关系 。Web Link 是 一 种 过 渡 型 链接 (Transitional Links) 。JAX-RS 2.0 引 入 了 
javax.ws.rs.core.Link 类 ， 用 来 处 理 Web Link 的 表述 。 


“ HATEOAS (Hypermedia as the Engine of Application State， 超 媒体 作为 应 用 程序 状态 引擎 ) 。HATEOAS 的 形式 是 包含 链接 信息 的 超 媒体 文档 。HATEOAS 的 核心 是 “引擎 ”， 该 引擎 的 目的 是 通过 请 求 
的 响应 实体 将 超 媒体 信息 返回 给 客户 端 ， 超 媒体 信息 可 以 告诉 用 户 ， 如 果 接 下 来 选择 去 往 某 个 链接 〈 或 者 链接 列表 中 的 某 个 链接 ) ， 应 用 的 状态 就 会 如 超 媒体 描述 的 那样 发 生 转变 。HATEOAS 是 一 种 结构 
型 链接 (Structural Links) 。Jersey 2 中 可 以 使 用 XML 实现 HATEOAS 的 结构 要 求 。 


下 面 讲 述 Jersey 中 是 如 何 实现 Web Link 和 HATEOAS 这 两 种 REST 连 通 性 实践 方式 的 。 


© 阅读 指南 。3.4 节 示例 所 在 目 录 是 jax-rs2-guide\sample\3\simple-service-3。 
源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : com.example.link。 


3.4.1 ”过 渡 型 链接 
Web Link 通 过 使 用 HTTP 的 头 信息 来 传递 操作 链接 ， 在 Jersey 中 使 用 avax.ws.rs.core.Link 类 可 以 非常 简洁 地 实现 支持 Web Link 的 资源 类 ， 示 例 代码 如 下 。 


Q@Path ("weblink-resource") 
public class WebLinkResource { 
@Context 
UriInfo uriInfo; 
@POST 
@Produces (MediaType .APPLICATION XML) 
@Consumes ( 
{ MediaType.APPLICATION JSON, MediaType.APPLICATION XML, MediaType.TEXT XML }) 
public Response saveBook(final Book book) { 加 
final long newId = System.nanoTime () 7 
book.setBookId (newId); 
LinkCache.map.put (newId, book); 
df 
关注 点 1 
: 通过 uriInfo 
实例 获取 资源 路 径 
final UriBuilder ub = uriInfo.getAbsolutePathBuilder (); 
final URI location = ub.path("" + newId) .build(); 


dd 

关注 点 2 

: 通过 模板 获取 资源 路 径 
final String uriTemplate = "http://{host}:{port}/{path}/{param}"; 
final URI location2 = UriBuilder.fromUri (uriTemplate) 
.resolveTemplate ("host", "localhost") .resolveTemplate ("port", "9998") 
.resolveTemplate ("path", "weblink-resource") 
.resolveTemplate ("param", newId) .build(); 


// 


人 
模板 方法 获取 资源 路 径 
final UriBuilder ub3 = uriInfo.getAbsolutePathBuilder(); 
final URI location3 = ub3.scheme ("http") .host ("localhost") .port (9998) 
.Path ("weblink-resource") .path("" + newId) .build(); 
// 


关注 点 4 

: 为 响应 实例 添加 路 径 信息 
return Response.created (location) .link (location2, "viewl") 
.link (location3, "view2") .entity (book) .build(); 


过 


向 秀 
hm 


在 这 段 代 码 中 ， 使 用 了 3 种 方式 构建 URI 实 例 。 第 一 种 方式 是 通过 调用 urilnfo 实 例 的 getAbsolutePathBuilder() 方 法 可 以 获取 当前 请 求 的 绝对 路 径 ， 然 后 基于 此 路 径 添加 资源 ID 信息 ， 见 关注 点 1。 第 二 
种 方式 是 为 UriBuilder 提 供 路 径 模板 ， 然 后 链 式 调用 resolveTemplate() 方 法 传递 并 解析 模板 参数 ， 最 后 通过 UriBuilder 的 build() 方 法 生成 URI 实 例 ， 见 关注 点 2。 第 三 种 方式 和 第 二 种 类 似 ， 不 同 的 是 模板 信 
息 被 具体 方法 替代 ， 见 关注 点 3。 最 后 ， 这 3 个 与 Link 相 关 的 URI 实 例 由 Response 构 建 ， 作 为 返回 值 响应 给 客户 端 ， 见 关注 点 4。 


回 


3.4.2 ”结构 型 链接 


HATEOASs 用 以 代替 聚集 数据 并 避免 描述 膨胀 ， 通 常 使 
的 资源 类 示例 如 下 。 


Atom 格 式 在 实体 字段 中 提供 链接 信息 。 本 例 使 用 XML 格式 来 支持 HATEOAS， 折 中 的 设计 是 在 POJO 中 额外 定义 一 个 链接 字段 。 支 持 HATEOAS 


QPath ("hateoas-resource") 
public class HATEOASResource { 
QContext 
UriInfo uriInfo; 
Q@POST 
Q@Produces ({ MediaType.APPLICATION XML }) 
@Consumes ({ MediaType.APPLICATION XML }) 
Public BookWrapper saveBook (final Book book) { 
final long newId = System.nanoTime (); 
book. setBookId (newId); 
LinkCache.map.put (newId, book); 


WV 

关注 点 1 

: 通过 uriInfo 

实例 获取 资源 路 径 
final UriBuilder ub = uriInfo.getAbsolutePathBuilder (); 
final URI uri = ub.path("" + newId) .build(); 
BookWrapper b = new BookWrapper (); 
b.setBook (book); 


关注 点 2 

: 将 资源 路 径 赋 给 资源 实体 
b.setLink (uri.toString()); 
return b; 


在 这 段 代码 中 ，URI 实 例 由 上 下 文 urilnfo 中 获取 的 绝对 路 径 和 资源 1D 组 成 ， 见 关注 点 1， 该 链接 信息 被 赋值 到 POJO 实 例 的 link 属 性 中 ， 以 实现 HATEOAS， 见 关注 点 2。 
宅 人 坑 事 


REST 连 通 性 的 实践 手段 非常 多 ， 推 荐 读者 从 成 误 的 产品 中 学 习 其 设计 。 如 果 有 可 能 ， 这 里 推荐 Jenkins 和 RallyDev 两 个 敏捷 开发 中 常用 的 平台 ， 它 们 提供 了 比较 “舒适 ”的 连通 性 设计 。 比 如 在 RallyDev 
中 ， 为 一 个 测试 用 例 结果 添加 测试 用 例 属 性 〈 该 属性 是 必须 输入 项 ) ， 其 内 容 并 不 是 对 应 测试 用 例 的 实例 ， 而 是 该 测试 用 例 的 引用 地 址 字符 串 。 这 样 的 设计 不 但 减少 了 网 络 传输 的 负载 ， 还 方便 在 调试 和 维 
护 时 排 错 。 


3.5 REST 响 应 处 理 


回 


REST 的 响应 处 理 结果 应 包括 响应 头 中 HTTP 状 态 码 ， 响 应 实体 中 媒体 参数 类 型 和 返回 值 类 型 ， 以 及 异常 情况 处 理 。JAX-RS 2.0 支 持 4 种 返回 值 类 型 的 响应 ， 分 别 是 无 返 
回 GenericEntity 类 实例 和 返回 自 定义 类 实例 。 下 面 ， 逐 一 讲述 这 4 种 返回 值 类 型 。 


值 、 返 回 Response 类 实例 、 返 


合计 指南 3.5 节 示例 所 在 目录 是 jax-rs2-guide\sample\3\simple-service-3。 
源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 
相关 包 : com.example.response。 

3.5.1 ”返回 类 型 


(1) void 


在 返回 值 类 型 是 void 的 响应 中 ， 其 响应 实体 为 空 ，HTTP 状 态 码 为 204。 在 前 面 的 DELETE 方 法 讲述 中 已 经 介绍 过 ， 再 来 看 一 下 这 种 类 型 的 资源 方法 。 


@DELETE 
@Path("{s}") 


六 

关注 点 1 

: 无 返回 值 的 DELETE 

方法 

Public void delete (@PathParam("s") final String s) { 
LOGGER. debug (s); 

} 


因为 delete() 方 法 无 须 返 回 更 多 的 关于 资源 表述 的 信息 ， 所 以 该 方法 没有 返回 值 ， 即 返回 值 类 型 为 void， 见 关注 点 1。 
(2) Response 


在 返回 值 类 型 为 Response 的 响应 中 ， 响 应 实体 为 Response 类 的 entity() 方 法 定义 的 实体 类 实例 。 如 果 该 内 容 为 空 ， 则 HTTP 状 态 码 为 204， 否 则 HTTP 状 态 码 为 200 OK。 示 例 代 码 如 下 。 


Q@POST 

@Path ("c") 

public Response get (final String s) { 
LOGGER.debug (s); 
//Response.noContent () .build(); 

// 


关注 点 1 
: 构建 无 返回 值 的 响应 实例 

return Response.ok() .entity("char[]:" + s) .build(); 
} 


在 这 段 代码 中 ，Response 首 先 定义 了 HTTP 的 状态 码 为 ok， 然 后 填充 实体 信息 ， 最 后 调用 build0) 方 法 构建 Response 实 例 ， 见 关注 点 1。 


(3) GenericEntity 


回 


通用 实体 类 型 作为 返回 值 的 情况 并 不 常用 。 其 形式 是 构造 一 个 统一 的 实体 实例 并 将 其 返回 ， 实 体 实例 作为 第 一 个 参数 ， 该 实体 类 型 作为 第 二 个 参数 。 示 例 代码 如 下 。 


Q@POST 
@Path ("b") 
public String get (final byte[] bs) { 
for (final byte b : bs) { 
LOGGER. debug (b); 


return "byte[]:" + new String (bs); 
A 
Public GenericEntity<String> get (final byte[] bs) { 


for (final byte b : bs) { 
LOGGER .debug (b); 


. 
ee 
关注 点 1 
: 构建 GenericEntity 
实例 
return new GenericEntity<String> ("byte[]:" + new String(bs), String.class); 
4 


在 这 段 代 码 中 ，GenericEntity 的 第 一 个 参数 是 由 byte 数 组 实例 作为 参数 构建 的 字符 串 实例 ， 第 二 个 参数 是 字符 串 类 ， 见 关注 点 1。 


(4) 自 定义 类 型 


JDK 中 的 类 (比如 File、String 等 ) 都 可 以 作为 返回 值 类 型 ， 更 常用 的 是 返回 自 定义 的 POJO 类 型 ， 前 述 多 个 例子 就 是 这 样 做 的 。 下 面 再 来 看 一 个 示例 。 


@POST 
@Path ("f") 


wf 
关注 点 1 


: GET 
方法 的 返回 类 型 为 File 
public File get (final File f) throws FileNotFoundException, IOException { 
try (BufferedReader br = new BufferedReader (new FileReader(f))) { 
Strinyg Ss 
dof{ 
s = br.readLine(); 
LOGGER. debug (s); 
} while (s != null); 
return f; 


} 


} 

Q@POST 

Q@Consumes ( {MediaType .APPLICATION XML,MediaType.APPLICATION JSON}) 
Q@Produces (MediaType .APPLICATION XML) 


// 

关注 点 2 

: POST 

方法 的 返回 值 是 自 定义 类 Book 

public Book getEntity (Book book) { 
LOGGER. debug (book.getBookName () ); 
return book; 


} 

Q@POST 

QConsumes ({MediaType.APPLICRATION XML,MediaType.APPLICATION JSON}) 
QProduces (MediaType .APPLICATION XML) 


ee 

关注 点 3 

: POST 

方法 的 返回 值 是 自 定义 类 Book 

public Book getEntity (JAXBElement<Book> bookElement) { 
Book book = bookElement .getValue(); 
LOGGER. debug (book .getBookName () ); 
return book; 


} 


在 这 段 代码 中 ， 返 回 值 类 型 有 来 自 JDK 的 File 类 型 ， 见 关注 点 1， 也 有 自 定义 的 POJO 类 型 ， 见 关注 点 2 和 关注 点 3。 


3.5.2 ”处 理 异 常 


实现 REST 的 资源 方法 时 应 使 其 具有 良好 的 异常 处 理 能 力 ， 这 包括 异常 的 定义 和 错误 状态 码 的 正确 返回 。 


1. 处 理 状态 码 


首先 通过 表 3-7 了 解 一 下 REST 中 常用 的 HTTP 状 态 码 ， 我 们 应 当 在 处 理 异常 的 同时 ， 为 REST 请 求 的 客户 端 提 供 对 应 的 状态 码 。 


状态 码 
200 OK 
201 Created 
202 Accepted 
204 No Content 
301 Moved Permanently 
302 Found 
304 Not Modified 
400 Bad Request 
401 Unauthorized 
403 Forbidden 
404 Not Found 
405 Method Not Allowed 
406 Not Acceptable 
$500 Internal Server Error 


301 Not Implemented 


表 3-7 ”HTTP 常用 状态 码 列表 


含义 
服务 器 正常 响应 
创建 新 实体 ， 响 应 头 Location 指定 访问 该 实体 的 URL 
服务 器 接收 请 求 ， 处 理 尚未 完成 。 可 用 于 异步 处 理 机 制 
服务 天 正常 响应 ， 但 响应 实体 为 空 
请 求 资 源 的 地 址 发 生 永 久 变动 ， 响 应 头 Location 指定 新 的 URL 
请 求 资源 的 地 址 发 生 临 时 变动 
客户 端 缓存 资源 依然 有 效 
请 求 信息 出 现 语法 错误 
请 求 资源 无 法 授权 给 未 验证 用 户 
请 求 资源 未 授权 当前 用 户 
请 求 资源 不 存在 
请 求 方法 不 匹配 
请 求 资源 的 媒体 类 型 不 匹配 
服务 需 内 部 错误 ， 意 外 终止 啊 应 
服务 器 不 支持 当前 请 求 


JAX-RS 2.0 规 定 的 REST 式 的 Web 服 务 的 基本 异常 类 型 为 运行 时 异常 WebApplicationException 类 。 该 类 包含 3 个 主要 的 子 类 ， 分 别 对 应 : 
"HTTP 状态 码 为 3xx 的 重 定向 类 RedirectionException。 
HTTP 状态 码 为 4xx 的 请 求 错误 类 ClientErrorException。 
“HTTP 状态 码 为 5xx 的 服务 器 错误 类 ServerErrorException。 


它们 各 自 的 子 类 对 照 HTTP 状 态 码 再 细 分 ， 比 如 常见 的 HTTP 状 态 码 404 错 误 ， 对 应 的 错误 类 为 NotFoundException， 可 参考 图 3-4。 


除了 Jersey 提 供 的 标准 异常 类 型 ， 我 们 也 可 以 根据 业务 需要 自 定义 相关 的 业务 异常 类 ， 示 例如 下 。 


关注 点 1 
: 定义 WebApplicationException 


接口 实现 类 

public class Jaxrs2GuideNotFoundException extends WebApplicationException { 
Public Jaxrs2GuideNotFoundException() { 

ee 

关注 点 2 

; 定义 HTTP 


super (javax.ws.rs.core.Response.Status.NOT FOUND); 


public Jaxrs2GuideNotFoundException (String message) { 
super (message); 


} 


在 这 段 代 码 中 ，Jaxrs2GuideNotFoundException 类 继承 自 JAX-RS 2.0 的 WebApplicationException 类 ， 见 关注 点 1。 其 默认 构造 子 提供 了 HTTP 状 态 码 ， 其 值 为 Response.Status.NOT_ FOUND， 见 关 
注 点 2。 


4 © Dbiect 
a 四 Throwable 
4 人 Exception 
4 加 RuntimeException 
4 | WebApplicationException 
a © ClientErrorException 
BadRequestException 
ForbiddenException 
NotAcceptableException 
NotAllowedException 
NotAuthorizedException 
NotFoundException 
NotSupportedException 
a O° paramException 
OB’ CookieParamException 
B75 FormparamException 
OG” HeaderParamException 
» ©@* UriparamException 
© RedirectionException 
4 © ServerErrorException 


© InternalServerErrorException 


© ServiceUnavailableException 


图 3-4 Jersey 定义 的 异常 类 型 


2.ExceptionMapper 


Jersey 框 架 为 我 们 提供 了 更 为 通用 的 异常 处 理 方式 。 通 过 实现 ExceptionMapper 接 口 并 使 用 @Provider 注 解 将 其 定义 为 一 个 Provider， 可 以 实现 通用 的 异常 的 面向 切面 处 理 ， 而 非 针 对 某 一 个 资源 方法 


的 异常 处 理 ， 示 例如 下 。 


@Provider 
public class EntityNotFoundMapper 
implements ExceptionMapper<Jaxrs2GuideNotFoundException>{ 


: 定义 ExceptionMapper 
接口 实现 类 
QOverride 
public Response toResponse (final Jaxrs2GuideNotFoundException ex) { 


2 
并 返回 新 的 响应 实例 
return Response.status (404) .entity (ex.getMessage () ) .type ("text/plain") .build(); 


在 这 段 代 码 中 ，EntityNotFoundMapper 实 现 了 ExceptionMapper 接 口 ， 并 提供 了 泛 型 类 型 为 前 面 刚 定 义 的 Jaxrs2GuideNotFoundException 类 ， 见 关注 点 1。 当 响应 中 发 生 了 
Jaxrs2GuideNotFoundException 类 型 的 异常 时 ， 响 应 流程 就 会 被 拦截 并 补充 HTTP 状 态 码 和 异常 消息 ， 以 文本 作为 媒体 格式 返回 给 客户 端 ， 见 关注 点 2。 


3.6 ”REST 内 容 协商 


~ 
阅读 指南 。3.6 节 示例 所 在 目 录 是 jax-rs2-guide\sample\3\simple-service-3。 
源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/3/simple-service-3。 


相关 包 : com.example.conneg。 


一 个 资源 可 以 有 不 同 格式 的 表述 ， 表 述 ( 即 响 应 实体 ) 的 内 容 是 人 类 可 识别 的 信息 ， 服 务 器 很 难 使 用 一 种 表述 来 适应 所 有 用 户 。conneg (HTTP Content Negotiation， 内 容 协 商 ) 是 指 在 服务 器 提供 
的 多 种 表述 中 ， 为 特定 的 请 求 选择 最 好 的 一 种 表述 的 处 理 过 程 。 那 么 什么 是 最 好 ， 又 怎样 做 到 最 好 呢 ? 服务 器 和 客户 端 /浏览 器 之 间 往 复 通信 来 协商 用 于 交换 数据 的 内 容 格式 等 信息 ， 达 成 一 致 即 为 最 好 。 内 


容 协商 定义 在 RFC 2616 的 第 12 节 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) 。 


客户 端 /浏览 器 通过 使 用 HTTP Accept、Accept-Charset、Accept-Language 和 Accept-Encoding 头 来 定义 接收 头 的 信息 ， 将 其 所 期 待 的 格式 或 MIME 类 型 告知 服务 器 ， 服 务 器 根据 协商 算法 ， 
户 端 /浏览 器 可 接收 的 数据 信息 。 内 容 协商 不 只 是 数据 格式 协商 ， 还 包括 语言 、 编 码 、 字 符 集 等 信息 。Accept 用 于 数据 类 型 协商 ，Accept-Language 用 于 语言 协商 ，Accept-Charset 用 于 字符 集 协 
商 ，Accept-Encoding 用 于 压缩 算法 协商 。 


JAX-RS 2.0 对 内 容 协商 的 支持 ， 是 通过 @Produces 实 现 的 ， 对 于 其 他 协商 ， 没 有 从 架构 上 提供 支持 ， 可 以 通过 编码 从 请 求 头 中 获取 信息 并 处 理 。 


3.6.1 _ @Produces 注 解 


注解 @Produces 用 于 定义 方法 的 响应 实体 的 数据 类 型 。 可 以 定义 一 个 或 多 个 ， 同 时 可 以 为 每 种 类 型 定义 质量 因素 (quality factor) 。 质 量 因素 是 取 值 范围 从 0~ 1 的 小 数值 。 如 果 不 定义 质量 因 


册 


该 类 型 的 质量 因素 默认 为 1。 我 们 将 结合 示例 深入 了 解 @Produces 注 解 对 媒体 类 型 的 影响 ， 代 码 如 下 。 


返回 客 


素 ， 那 么 


@Path ("conneg-resource") 
public class ConnegResource { 
QGET 
@Path ("{id}") 


// 
关注 点 1 
: 媒体 类 型 为 XML 
Q@Produces (MediaType .APPLICATION XML) 
public Book getJaxbBook (@PathParam("id") final Long bookId) { 
return new Book (bookId); 
} 
@GET 
@Path ("{id}") 
a 
关注 点 2 
: 媒体 类 型 为 JSON 
QProduces (MediaType .APPLICATION JSON) 
Public Book getJsonBook (GPathParam("id") final Long bookId) { 
return new Book (bookId) 7 


} 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 


在 这 段 代码 中 ，getJaxbBook0 和 getJsonBook() 是 同等 质量 因素 、 资 源 地址 相同 的 两 个 GET 方 法 ， 一 个 定义 响应 实体 格式 为 XML， 另 一 个 定义 响应 实体 格式 为 JJON， 分 别 见 关注 点 1 和 关注 点 2。 那 么 
对 同一 个 资源 的 访问 ，JAX-RS 2.0 该 如 何 选择 处 理 方法 呢 ? 如 果 请 求 中 明确 定义 可 接收 的 数据 类 型 为 两 者 之 一 ， 那 么 处 理 方法 应 该 是 定义 相应 数据 类 型 的 那个 方法 。 如 果 两 者 都 定义 了 ， 那 么 处 理 方法 应 该 


是 质量 因素 高 的 那个 方法 。 如 果 两 者 都 定义 ， 而 且 数 据 类 型 的 质量 因素 是 相等 的 ， 或 者 没有 定义 Accept， 那 么 XML 的 方法 会 被 优先 选择 。 


客户 端 明确 表 述 格式 为 XML，Jersey 通 过 内 容 协 商 ， 会 选择 getJaxbBook() 作 为 相应 的 资源 方法 来 处 理 该 请 求 。 其 测试 代码 如 下 所 示 。 


WebTarget path = target ("conneg-resource") .path ("123"); 

Builder request = path.request (MediaType.APPLICATION XML TYPE); 

Book book = request.get (Book.class); 

1 > GET http://localhost:9998/conneg-resource/123 

1 > Accept: application/xml 

2 < Content-Type: application/xml 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book bookId="123"/> 


接 下 来 ， 测 试 一 个 稍微 复杂 的 内 容 协商 。 客 户 端 明确 表 述 格式 的 质量 因素 JSON 高 于 XML，Jersey 会 选择 资源 方法 getjsonBook() 来 处 理 请 求 。 其 测试 代码 如 下 所 示 。 


WebTarget path = target ("conneg-resource") .path ("123"); 

Builder request = path.request (); 

request .header ("Accept", "application/xml;q=0.1,application/json;q=0.2"); 
Book book = request.get (Book.class); 

1 > GET http://localhost:9998/conneg-resource/123 

1 > Accept: application/xml;q=0.1,application/json;q=0.2 

2 < Content-Type: application/json 

{"bookId":123} 


现在 我 们 清楚 了 两 个 同等 方法 的 场景 ， 再 来 看 一 下 一 个 方法 中 多 种 数据 类 型 的 场景 ， 示 例 代 码 如 下 。 


@GET 

Q@Produces 

({ "application/json; qs=.9", "application/xml; qs=.5" } 
) 


@Path 
("book/{id}" 
》 


Public Book getBook 
(@PathParam 

(nid" 

) final Long bookId 
) { 


return new Book 
(bookId 
) 3; 
} 


在 这 段 代 码 中 ，getBook0) 方 法 定义 了 XML 和 JSON 两 种 表述 数据 类 型 ，XML 的 质量 因素 是 0.5 (0 可 以 省 略 ) ，JSON 的 是 0.9。 


因此 ,我 们 可 以 推断 ， 如 果 客户 端 请 求 中 明确 接收 的 数据 类 型 是 两 者 之 一 ， 那 么 响应 实体 使 
类 型 。 还 有 一 种 


指定 类 型 。 如 果 没 有 定义 或 者 两 者 都 定义 且 JSON 的 质量 
例 是 ， 两 者 都 定义 但 JSON 的 质量 因素 小 于 XML 的 质量 因素 ， 该 如 何 处 理 请 求 方法 呢 ? 答案 是 内 容 协商 的 结果 按照 客户 端的 喜好 选择 响应 实体 的 数据 类 型 ， 即 选择 XML 格式 。 


其 测试 代码 如 下 所 示 ， 客 户 端 明确 表 述 格式 XML 优 于 JSON。 虽 然 服务 器 端 定义 的 资源 方法 中 JSON 的 质量 因素 高 ， 但 Jersey 会 根据 客户 端的 喜好 ， 选 择 了 XML 格式 作为 表述 的 格式 返回 。 


因素 大 于 或 者 等 于 XML 的 质量 


素 ， 则 返回 JSON 


WebTarget path = target 
("conneg-resource" 

) .path 

("book" 

) .path 

("123" 

) ; 

Builder request = path.request (); 

request .header 

("Accept", "application/xml;q=0.7,application/json;q=0.2" 
3 


Book book = request.get 

(Book.class 

); 

1 > GET http://localhost:9998/conneg-resource/book/123 

1 > Accept: application/xml;q=0.7,application/json;q=0.2 

2 < Content-Type: application/xml 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><book bookId="123"/> 


3.6.2”@Consumes 注 解 


注解 @Consumes 
务 器 会 返回 HTTP 状 态 码 415 (Unsupported Media Type) 。 其 示例 代码 如 下 。 


POST 
aa 
关注 点 1 


: @Consumes 
注解 定义 了 XML 
和 JSON 
两 种 格式 
QConsumes ( {MediaType .APPLICATION XML,MediaType.APPLICATION JSON}) 
@Produces (MediaType .APPLICATION XML) 
public Book getEntity (Book book) { 
LOGGER. debug (book .getBookName () ); 
return book; 


} 

final Builder request = target (path) .request (); 
ea 

关注 点 2 


final Book result = request.post( 
Entity.entity (book, MediaType.APPLICATION XML), Book.class); 


于 定义 方法 的 请 求实 体 的 数据 类 型 。 和 @Produces 不 同 的 是 ，@Consumes 的 数据 类 型 的 定义 只 用 于 JAX-RS 2.0 匹 配 请 求 处 理 的 方法 ， 不 做 内 容 协商 使 用 。 如 果 匹 配 不 到 ， 那 么 服 


在 这 段 代 码 中 ，getEntity0 方 法 定义 了 @Consumes 媒 体 类 型 为 XML 格 式 和 JSON 格 式 ， 见 关注 点 1。 那 么 ， 在 客户 端 请 求 中 ， 如 果 请 求实 体 的 数据 类 型 定义 为 两 者 之 一 ， 那 么 该 方法 会 被 选择 为 处 理 请 


求 的 方法 ， 否 则 查找 是 否 有 定义 为 相应 数据 类 型 的 方法 ， 如 果 没 有 抛 出 javax.ws.rs.NotSupportedException 异 常 ， 则 使 


该 方法 处 理 请 求 ， 见 关注 点 2。 


3.7 本章 小 结 


本 章 是 REST 理 论 和 Jersey 实 践 的 核心 章节 ， 


详细 讲述 了 HTTP 方 法 与 REST API 的 统一 接口 设计 、URI 的 REST 风 格 设计 ， 


并 逐个 讲述 了 JAX-RS 2.0 定 义 的 注解 如 何 支持 资源 定位 ， 还 讲述 了 Jersey 对 各 种 


表述 类 型 的 支持 和 实现 、Jersey 对 REST 连 通 性 的 两 种 实现 、REST 资 源 方法 对 响应 的 处 理 ， 以 及 Jersey 对 内 容 协商 的 支持 和 实现 。 接 下 来 ， 我 们 走 进 JAX-RSs 定 义 的 各 种 Providers， 更 深入 地 了 解 过 滤 、 拦 截 


等 功能 的 实现 。 


第 4 章 ”REST 请 求 处 理 


设计 良好 的 REST API 除 了 要 符合 关于 统一 接 
扩展 点 ， 并 讲述 如 何 对 其 实现 。 


和 资源 定位 等 要 求 ， 还 要 详细 考虑 通 


图 半 读 指南 本 章 示 例 所 在 目录 是 jax-rs2-guide\sample\4\jaxrs2-handle。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/4/jaxrs2-handle。 


4.1 REST 和 AOP 


AOP 对 增强 REST 式 的 Web 服 务 的 功能 性 、 安 全 性 和 可 扩展 性 等 方面 都 


有 深远 意义 ， 因 此 ， 


的 请 求 处 理 过 程 中 ， 每 个 步骤 的 特殊 处 理 ， 并 设计 出 符合 业务 规范 的 处 理 流程 。 本 章 将 深入 REST 请 求 处 理 过 程 中 的 


% 整 的 REST 风 格 的 框架 都 从 容器 级 别 支持 AOP 式 的 开发 。Jersey 可 以 在 不 依赖 于 Spring 等 AOP 支 持 框架 的 


情况 下 ， 天 然 地 支持 AOP。 


小 白 讲堂 


AOP (Aspect Oriented Programming， 面 向 切面 编程 ) 的 典型 应 用 场景 有 权限 管理 、 日 志 记 录 、 统 计 记 录 、 事 务 以 及 异常 处 理 等 。 其 实现 原理 是 代理 被 调用 的 方法 ， 在 其 被 执行 的 方法 前 后 ， 增 加 额外 业 
务 功能 。AOP 的 实现 机 制 是 通过 注解 或 者 XML 配置， 依据 这 些 配 置 ， 动 态 生 成 字 节 码 (bytecode) ， 使 调用 代码 对 应 的 字 节 码 被 环绕 注入 新 的 功能 ; 或 者 使 用 Java 的 动态 代理 机 制 ， 完 成 对 被 调用 方法 的 增 


强 。 


Jersey 的 AOP 功 能 来 自 于 GlassFish 项 目 集 的 HK2 项 目 (参见 1.4 节 ) 。Jersey 通 用 包 jersey-common 依 赖 HK2 ( 轻 量 级 DI 架构 ) ， 包 括 hk2-api 和 hk2-locator。 


其 中 hk2-locator 依 赖 于 javax.inject 包 、asm-all-repackaged 包 和 cglib 包 。 从 这 些 包 名 不 难看 出 ，hk2-locator 是 个 致力 于 AOP 方 向 的 包 。javax.inject 包 出 


Spring 
自 中 国 的 OrientWare 两 个 中 间 件 开源 组 织 。 


Jersey 提 供 的 REST 过 滤器 和 拦截 器 为 开发 者 提供 了 很 贴心 的 切面 扩展 点 ， 开 发 者 无 须 像 在 Spring 中 为 了 针对 某 个 类 


户 熟 识 的 动态 代码 生成 工具 ， 是 Spring 两 种 AOP 实 现 方式 的 一 种 ， 其 底层 依赖 于 ASM。ASsM 来 自 于 开源 软件 国际 联盟 OW2 (http://www.ow2.org) ，OW2 的 前 身 是 来 自 法 国 


的 方法 进行 AOP 扩 


实现 REST 请 求 流程 中 特定 事件 点 的 拦截 、 扩 展 ， 其 他 工作 由 底层 的 HK2 帮 我 们 做 。 典 型 的 应 用 包括 请 求 和 响应 的 过 滤 和 读 写 拦截 。 


4.2 Providers 详 解 


Java 依 赖 注入 规范 (JSR-330) ，cglib 是 


的 ObjectWeb 和 来 


展 而 写 配 置 文件 。 在 Jersey 中 ， 只 要 实现 相应 扩 


展 点 的 接口 ， 即 可 


javax.ws.rs.ext.Providers 是 JAX-RS 2.0 定 义 的 一 种 辅助 接口 ， 其 实现 类 用 于 辅助 REST 框 架 完 成 过 滤 和 读 写 拦截 等 功能 。 使 用 注解 @Provider 来 标注 这 些 实现 类 ， 可 以 被 JAX-RS 2.0 的 运行 时 自动 探测 、 


加 载 。Provider 实 例 可 以 通过 @ Context 注 解 被 依赖 注入 到 
ContextResolver 实 例 。 


4.2.1 实体 Providers 


在 3.3 节 我 们 讲述 了 Jersey 支 持 的 各 种 传输 格式 。Jersey 之 所 以 可 以 支持 那么 多 种 表述 的 类 型 ， 即 响应 实体 的 传输 格式 ， 是 因为 其 底层 实体 Providers 具 备 的 对 不 同 格式 的 处 理 能 力 。 如 


示 ，Jersey 内 部 提供 了 非常 丰富 的 MessageBodyReader 接 口 和 MessageBodyWriter 接 口 实现 类 ， 用 于 处 理 不 同 格式 的 表述 ， 比 如 字 节 数组 、XML、 文 件 和 流 等 。 本 节 将 介绍 读 写实 体 的 工具 类 


MessageBodyReader 和 MessageBodyWriter， 并 为 我 们 业务 所 用 。 


他 实例 中 。Providers 接 口 定义 了 4 个 方法 ， 分 别 用 来 获取 MessageBodyReader、MessageBodyWriter、ExceptionMapper 和 


4-1 所 


4 | 哆 “MessageBodyReader<T>| 
4 © AbstractMessageReaderWriterProvider<T> 
4 回 * AbstractFormprovider<T> 
OF FormMultivaluedMapProvider 
OF Formprovider 
4 © AbstractJaxbProvider<T> 
4 © AbstractCollectionJaxbProvider 
4 © XmlCollectionJaxbProvider 
GF App 
SF General 
GF Ted 
4 © AbstractjaxbElementprovider 
4 © XmlaxbElementprovider 
GF App 
© General 
GF Ted 
4 回 * AbstractRootElementjaxbprovider 
4 © XmlRootElementJaxbProvider 
GF App 
© General 
GF Texd 
4 © XmlRootObjectJaxbProvider 
Gr App 
© General 
GF Ted 
GQ BasicTypesMessageProvider 
© ByteArrayprovider 
© DataSourceProvider 
OF Documentprovider 
©" Fileprovider 
OF InputStreamprovider 
OF Readerprovider 
加 上 RenderedimageProvider 
GQ StringMessageprovider 
GQ ChunkedInputReader 
3 DomSourceReader 
4 © MOXyjsonprovider 
© ConfigurableMoxyJsonProvider 
HF SaxSourceReader 
IF StreamSourceReader 


4 I MessageBodyWriter<T> 
4 © AbstractMessageReaderWriterProvider<T> 
4 © AbstractFormPprovider<T> 
加 5 FormMultivaluedMapProvider 
OF Formprovider 
4 回 * AbstractJaxbprovider<T> 
4 加 4 AbstractCollectionjJaxbprovider 
4 加 "XmlCollectionjJaxbprovider 
GF App 
3F General 
GF Ted 
4 ©O* AbstractjaxbElementprovider 
4 四 * XmlaxbElementprovider 
对 ”App 
3F General 
OF Ted 
4 回 * AbstractRootElementjaxbprovider 
4 © XmlRootElementjaxbprovider 
GF App 
IF General 
GF Texd 
4 © XmlRootObjectJaxbProvider 
个” App 
© General 
GF Tect 
Co BasicTypesMessageProvider 
OF ByteArrayprovider 
© DataSourceProvider 
OF Documentprovider 
© Fileprovider 
OF Inputstreamprovider 
OF Readerprovider 
OF RenderedlmageProvider 
QF stringMessageProvider 
© ChunkedResponseWriter 
4 © MOXyjsonprovider 
© ConfigurableMoxyJsonProvider 
GF SourceWriter 
OF streamingOutputProvider 


图 4-1 MessageBodyReader 和 MessageBodyWriter 的 实现 类 


1.MessageBodyReader 


消息 体 读 处 理 器 接口 MessageBodyReader<T> 


于 将 传输 流转 换 为 Java 类 型 的 对 象 。MessageBodyReader 接 口 


定义 了 一 个 泛 型 ， 接 口 


的 实现 类 为 这 个 泛 型 定义 一 个 具体 类 型 ， 该 类 型 即 是 该 实现 类 


所 支持 的 转换 类 型 。 实 现 类 被 业务 系统 启用 有 两 种 方式 ， 一 种 是 使 用 注解 @Provider 定 义 实现 类 ， 业 务 系统 在 启动 时 自动 探测 并 加 载 ， 另 一 种 是 通过 编码 注册 到 Application 类 或 其 子 类 中 ， 业 务 系统 在 启动 


时 ， 加 载 Application 类 或 其 子 类 时 一 并 加 载 。 


(1) isReadable 


MessageBodyReader<T> 接 


会 判断 当前 类 型 是 否 是 字 节 数组 类 型 ， 示 例 代 码 如 下 所 示 。 


定义 了 两 个 方法 。 第 一 个 方法 isReadable() 用 来 判断 实现 类 是 否 支 持 将 当前 请 求 的 数据 类 型 反 序列 化 。 以 读 取 字 节 数组 实体 实现 类 ByteArrayProvider 为 例 ， 其 覆盖 方法 


//isReadable 
接口 方法 


Public boolean isReadable (Class<?> type, Type genericType,Annotation[] annotations, MediaType mediaType); 


//isReadable 
方法 的 实现 


QOverride 


Public boolean isReadable (Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) { 


return type == byte[] .class; 
} 


J 

测试 方法 运行 时 栈 

org.glassfish.jersey.message.internal .ByteArrayProvider. 

isReadable (ByteArrayProvider.java:66) 

org.glassfish.jersey.message.internal .MessageBodyFactory$MbrModel. 

isReadable (MessageBodyFactory .java:250) 

org.glassfish.jersey.message.internal .MessageBodyFactory$MbrModel. 

isReadable (MessageBodyFactory .java:243) 

org.glassfish.jersey.message.internal .MessageBodyFactory 

._getMessageBodyReader (MessageBodyFactory.java:744) 

org.glassfish.jersey.message.internal .MessageBodyFactory 

.getMessageBodyReader (MessageBodyFactory .java:659) 

org.glassfish.jersey.message.internal .ReaderInterceptorExecutor$TerminalReaderIinterceptor. 

aroundReadFrom (ReaderInterceptorExecutor .java:194) 

org.glassfish.jersey.message.internal .ReaderIinterceptorExecutor. 

Proceed (ReaderInterceptorExecutor.java:139) 

org.glassfish.jersey.message.internal .MessageBodyFactory. 

readFrom (MessageBodyFactory.java:1109) 

org.glassfish.jersey.message.internal .InboundMessageContext. 

readEntity (InboundMessageContext .java:851) 

org.glassfish.jersey.message.internal.InboundMessageContext. 

readEntity (InboundMessageContext .java:785) 

org.glassfish.jersey.client.InboundJaxrsResponse.readEntity (InboundJaxrsResponse.java:96) 
org.glassfish.jersey.client.ScopedJaxrsResponse.access$001 (ScopedJaxrsResponse.java:56) 
org.glassfish.jersey.client.ScopedJaxrsResponse$1.call (ScopedJaxrsResponse.java:77) 
org.glassfish.jersey.internal .Errors.process (Errors.java:315) 
org.glassfish.jersey.internal .Errors.process (Errors.java:297) 
org.glassfish.jersey.internal .Errors.process (Errors.java:228) 
org.glassfish.jersey.process.internal .RequestScope.runInScope (RequestScope.java:397) 
org.glassfish.jersey.client .ScopedJaxrsResponse.readEntity (ScopedJaxrsResponse.java:74) 


从 测试 类 TestByteArrayReader 的 testReader() 方 法 运行 时 栈 中 可 以 追溯 到 Response 的 readEntity() 方 法 ， 从 这 期 间 的 调用 可 以 获得 MessageBodyReader 的 实现 类 在 Jersey 架 构 体 系 中 的 位 置 。 关 于 
MessageBodyReader 在 流程 中 的 位 置 可 以 参见 4.3 节 。 


(2) readFrom 


MessageBodyReader<T> 接 口 定义 的 第 二 个 方法 是 readFrom(0， 用 于 处 理 反 序 列 化， 是 处 理 读 取 流 并 转换 为 Java 类 型 对 象 的 核心 方法 。 方 法 定义 如 下 。 


Public T readFrom 

(Class<T> type, Type genericType,Annotation[] annotations, 
MediaType mediaType, MultivaluedMap<String, String> httpHeaders, 
InPutStream entityStream 

) throws java.io.IOException, javax.ws.rs.WebApplicationException; 


继续 读 取 字 节 数组 实体 实现 类 ByteArrayProvider 的 研究 ， 该 方法 的 覆 写 包含 两 个 内 容 。 第 一 是 将 实体 输入 流 写 入 字 节 数组 输出 流 ， 第 二 是 将 该 流 以 字 节 数组 的 形式 返回 。 运 行 单元 测试 类 
TestByteArrayReader， 并 在 ByteArrayProvider 类 中 设置 断 点 ， 可 以 监控 到 具体 的 行为 ， 可 参考 图 4-2。 


2.MessageBodyWriter 


消息 体 写 处 理 器 接口 MessageBodyWriter<T> 用 于 将 Java 类 型 的 对 象 转换 为 流 ， 是 序列 化 的 过 程 ， 是 MessageBodyReader<T> 接 口 实现 的 反 序列 化 的 逆 过 程 。 两 个 接口 的 设计 原理 是 相同 的 。 对 应 
的 ，MessageBodyWriter<T> 定 义 了 两 个 方法 ， 即 isWriteable0 和 writeTo0。 其 实 ， 解 析 一 种 传输 类 型 的 Provider 类 通常 会 同时 实现 MessageBodyReader 和 MessageBodyWriter 这 两 个 接口 ， 比 如 上 面 
提 及 的 ByteArrayProvider 类 。 


为 了 更 全 面 地 掌握 实体 Provider 实 现 类 序列 化 过 程 的 分 析 ， 我 们 选用 较为 复杂 的 MOXyJsonProvider 类 做 例子 。MOXyJsonProvider 类 是 第 3 章 讲述 的 4 种 JSON 支 持 技术 中 MOXy 的 支持 类 ， 来 自 
EclipseLink 项 目 。MOXyJsonProvider 类 实现 了 上 述 的 两 个 接口 ， 并 定义 了 生产 和 消费 的 媒体 类 型 。 


application/octet—streamn 
aCorsunmes ({” spplication/octet—stream”, 


public final class ByteArrayProvider extends AbstractllessageReaderWriterProvider<byte[]> { 


@Override 
public boolean isReadable (Class<?> type, Type genericlype, Annotation[] sannotations, Medialype medialype) { 
return type == byte[]. class:; 


QOverride 
public byte[] resadFrom( 
Class<byte[]> type, 
Type genericlype, 
Annotation annotations[], 
Medialype medialype, 
MultivaluedMap<Strine, Strine> httpHeaders, 
InputStream entityStream) throws IOException { 
ByteArrayOutputStream out = new BytehrrayOutputStresanm () : 
wzrzteTokentityStresam，out) 
return out. toByteArray().; 


} 


三 Variables 


entityStream = {org.glassfish.jersey.message.internal.EntityInputStream@2819} 
out = {ava.io.ByteArrayOutputStream@2820}"Hello”" 

齐 buf = {byte[32]@3330} 

count = 5 


| 


4-2 ”readFrom( 方 法 示例 


(1) isWriteable 


isWriteable() 方 法 用 于 检测 实现 类 是 否 支持 序列 化 当前 请 求 的 类 型 ， 如 果 不 可 写 ，Jersey 框 架 会 放弃 使 用 这 个 实现 类 来 处 理 当前 的 表述 。 在 分 析 ByteArrayProvider 类 的 可 读 实 现时 ， 该 方法 只 使 用 到 了 
第 一 个 参数 type， 而 在 MOXyjsonProvider 类 的 可 写 检测 的 覆 写 中 ， 同 时 用 到 了 最 后 一 个 参数 mediaType 来 校 验 请 求 的 媒体 类 型 是 否 是 JSON 类 型 。 示 例 代 码 如 下 所 示 。 


public boolean isWriteable (Class<?> type, 

Type genericType,Annotation[] annotations, MediaType mediaType); 

package org.eclipse.persistence.jaxb.rs 

@Produces ({MediaType.APPLICATION JSON, MediaType.WILDCARD, "application/x-javascript"}) 
@Consumes ({MediaType .APPLICATION JSON, MediaType .WILDCARD}) 

public class MOXyJsonProvider 

implements MessageBodyReader<Object>, MessageBodyWriter<Object>{ 

public boolean isWriteable (Class<?> type, 

Type genericType, Annotation[] annotations, MediaType mediaType) { 


/4 

关注 点 1 

: 对 type 

芍 校 验 ” 
if (type 一 JSONWithPadqing.class && APPLICATION XJAVASCRIPT 
.equals (mediaType.toString())) { 


return true; 


} 


// 
媒体 类 型 不 是 JSON 
类 型 ， 直 接 返 回 false 
if(!supportsMediaType (mediaType)) { 
return false;// 
类 型 是 字 节 数组 或 者 字符 串 类 型 ， 直 接 返 回 false 
} else if(CoreClassConstants.APBYTE == type || CoreClassConstants.STRING 一 type) { 
return false; 
} else if(File.class.isAssignableFrom(type)) { 
return false; 
} else if (DataSource.class.isAssignableFrom(type)) { 
return false; 
} else if(StreamingOutput.class.isAssignableFrom(type)) { 
return false; 
} else if(Object.class = type) { 
return false; 
} else if (JAXBElement.class.isAssignableFrom(type)) { 
Class domainClass = getDomainClass (genericType); 
return isWriteable (domainClass, null, annotations, mediaType) 
11 domainClass 一 String.class; 
} else if(Collection.class.isAssignableFrom(type)) { 
Class domainClass = getDomainClass (genericType); 
return isWriteable (domainClass, null, annotations, mediaType) 
11 domainClass 一 String.class; 
} else { 
return true; 


} 


在 这 段 代 码 中 ， 在 关注 点 1 处 ，MOXyJsonProvider 类 对 第 一 个 参数 type 类 型 的 校 验 条 件 繁多 ， 从 字 节 数组 到 Collection 类 的 子 类 ， 只 要 匹配 就 返回 false， 也 就 是 说 ，MOXyJsonProvider 类 不 负责 对 这 
些 类 型 进行 序列 化 操作 。 


(2) writeTo 


writeTo() 方 法 是 将 请 求 对 象 写 入 流 的 序列 化 过 程 。MOXyjsonProvider 类 的 writeTo 方 法 的 覆 写 内 容 有 30 多 行 ， 
示例 代码 如 下 。 


基本 都 是 对 Marshaller 实 例 的 配置 ， 关 键 的 一 行 是 执行 Marshaller 实 例 的 marshal 一 行 ， 


//writeTo 

接口 方法 : 

public void writeTo(T t, Class<?> type, Type genericType, Annotation[] annotations, 
MediaType mediaType, MultivaluedMap<String, Object> httpHeaders, 

OutputStream entityStream) throws java.io.IOException, javax.ws.rs.WebApplicationException; 
//MOXyJsonProvider 

类 的 writeTo 

方法 : 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


marshaller.marshal (object, entityStream); 


其 对 应 的 测试 栈 信息 如 图 4-3 所 示 。 


如 图 4-3 所 示 ， 从 测试 类 TestMoxyWriter 的 testMoxyWriter 方 法 的 栈 信息 中 ， 可 以 看 到 Book 实 例 被 序列 化 到 CommittingOutputStream 流 实例 中 ， 实 现 了 写 入 的 过 程 。 


号 MOXyjsonproviderjava x 


preWritelo (object, type, EenericTlype, 


marshaller, marshal (ob]ject 


entityStream 


} catch JAXBException jaxbException) { 


anmotations 


medialype, httpHeaders, marshaller) 


throw mew WebApplicationException (jaxbException) 


entityStream 
三 adaptedOutput = null 
国 bufferSize = 0 

三 buffer = null 
directWrite = true 
国 isCommitted = 和 lse 


图 isClosed = false 


图 4-3 ”writeTo 方 法 (0) 示例 


3.MessageBodyWorkers 


从 图 4-1 所 示 的 MessageBodyReader 和 MessageBodyWriter 的 实现 类 示意 图 中 可 以 看 出 ， 实 体 读 写 接 


上 述 的 isReadable 示 例 栈 中 ， 可 以 发 现 它 的 “ 


2 
惊人 。 


宅 人 坑 事 


{org.glassfish,jersey.message.internal.CommittingOutputStream@2788} 


streamProvider = {org.glassfish,ersey.client.HttpUrlConnector$3@3704)} 


的 实现 类 非常 多 ， 选 择 哪个 实现 类 作为 当前 请 求 的 读 写 处 理 器 的 算法 是 非常 繁重 的 工 
作 ，MessageBodyWorkers 接 口 则 在 抽象 这 一 遂 选 工作 ， 其 实现 类 可 以 通过 @ Context 依 赖 注入 到 使 用 MessageBodyWorkers 的 类 中 。MessageBodyFactory 是 MessageBodyWorkers 接 | 


的 实现 类 。 在 


实体 读 写 接口 定义 在 JAX-RS 2.0 的 javax.ws.rs.ext 包 中 ，MessageBodyWorkers 定 义 在 Jersey 核 心包 jersey-common 的 org.glassfish.jersey.message 包 中 ， 前 者 是 规范 定义 的 接口 ， 后 者 是 参考 实现 定义 的 接口 ， 不 要 


混 消 。 


4.2.2 上下文 Providers 


除了 处 理 实 体 的 Provider， 处 理 上 下 文 的 Provider 也 非常 重要 。ContextResolver<T> 接 口 即 是 用 于 提供 资源 类 和 其 他 Provider 上 下 文 信息 的 接口 。ContextResolver<T> 定 义 了 一 个 方法 


getContext0， 输 入 参数 是 表述 对 象 的 类 型 ， 输 出 是 上 下 文 泛 型 。 


我 们 来 回顾 一 下 3.3 节 讲述 的 JsonContextResolver 类 ， 其 是 ContextResolver 的 实现 类 ， 根 据 不 同 的 表述 类 型 ， 提 供 不 同 的 JAXB 上 下 文 类 JettisonJaxbContext 实 例 。 栈 信息 如 下 。 


T getContext 
(Class<?> type 

7 
com.example.resource.JsonContextResolver.getContext 
(JsonContextResolver.java:26 
) 


com.example.resource.JsonContextResolver.getContext 
(JsonContextResolver.java:12 

) 

org.glassfish.jersey.message.internal .AbstractJaxbProvider .getJAXBContext 
(AbstractJaxbProvider.java:244 

) 


org.glassfish.jersey.message.internal .AbstractJaxbProvider.getMarshaller 
(AbstractJaxbProvider.java:217 
) 


org.glassfish.jersey.message.internal.AbstractJaxbProvider.getMarshaller 
(AbstractJaxbProvider.java:184 
) 


org.glassfish.jersey.message.internal .AbstractRootElementJaxbProvider.writeTo 
(AbstractRootElementJaxbProvider.java:162 


com.example.resource.JsonContextResolver.getContext 


《JsonContextResolver.Jjava:26 


com.example.resource.JsonContextResolver.getContext 
(JsonContextResolver .java:12 
) 


org.glassfish.jersey.message.internal.AbstractJaxbProvider.getJAXBContext 
(AbstractJaxbProvider.java:244 
) 


org.glassfish.jersey.message.internal.AbstractJaxbProvider.getUnmarshaller 
(AbstractJaxbProvider.java:178 
) 


org.glassfish.jersey.message.internal.AbstractJaxbProvider.getUnmarshaller 
(AbstractJaxbProvider.java:154 
) 


org.glassfish.jersey.message.internal .AbstractRootElementJaxbProvider .readFrom 
(AbstractRootElementJaxbProvider.java:122 
) 
org.glassfish.jersey.message.internal .ReaderIinterceptorExecutor$TerminalReaderIinterceptor. 
invokeReadFrom 
(ReaderInterceptorExecutor.java:239 
) 


org.glassfish.jersey.message.internal .ReaderIinterceptorExecutor$TerminalReaderIinterceptor. 
aroundReagdFrom 

(ReaderInterceptorExecutor.java:211 
) 


org.glassfish.jersey.message.internal .ReaderIinterceptorExecutor .proceed 
(ReaderInterceptorExecutor.java:139 


org.glassfish.jersey.message.internal .MessageBodyFactory.readFrom 
(MessageBodyFactory.java:1109 
) 


从 栈 的 输出 中 可 以 观察 到 序列 化 过 程 ， 从 writeTo 到 getContext， 以 及 在 这 一 过 程 中 ， 从 readFrom 到 getContext 的 栈 信息 。 


除了 上 述 两 种 类 型 的 Provider，JAX-Rs 2.0 还 定义 了 处 理 异 常 的 Provider， 可 参考 3.5.2 节 。 


4.3 ”REST 请 求 流程 


在 REST 请 求 处 理 的 扩展 点 上 ， 我 们 已 经 讲述 了 实体 处 理 的 Provider 接 口 ， 以 及 上 下 文 处 理 和 异常 处 理 。 本 章 还 将 讲述 两 种 在 面向 切面 编程 中 非常 重要 的 、 特 殊 的 Provider: 过 滤器 (4.4 节 ) 和 拦截 器 
(4.5 节 ) 。 在 进入 这 个 主题 之 前 ， 我 们 需要 对 REST 请 求 处 理 的 流程 这 条 线 有 明确 的 认识 ， 这 样 一 来 ， 才 会 知道 这 些 点 都 处 于 流程 的 什么 位 置 。 只 有 这 样 才能 清楚 地 实现 对 扩展 点 的 开发 和 调试 。 


如 图 4-4 所 示 ， 请 求 流程 中 存在 3 种 角色 ， 分 别 是 用 户 、REST 客 户 端 和 REST 服 务 器 。 请 求 始 于 请 求 的 发 送 ， 止 于 调用 Response 类 的 readEntity( 方 法 ， 获 取 响 应 实体 。 
1) 用 户 提交 请 求 数据 ， 客 户 端 接收 请 求 ， 进 入 第 一 个 扩展 点 : “客户 端 请 求 过 滤器 ClientRequestFilter 实 现 类 ”的 filter() 方 法 。 
2) 请 求 过 滤 处 理 完毕 后 ， 流 程 进入 第 二 个 扩展 点 : “客户 端 写 拦截 器 Writerlnterceptor 实 现 类 ”的 aroundWriteTo() 方 法 ， 实 现 对 客户 端 序列 化 操作 的 拦截 。 


3) “客户 端 消 息 体 写 处 理 器 MessageBodyWriter” 执 行 序列 化 ， 流 程 从 客户 端 过 渡 到 服务 器 端 。 


4) 服务 器 接收 请 求 ， 流 程 进入 第 三 个 扩展 点 : “服务 器 前 置 请 求 过 滤器 ContainerRequest Filter 实 现 类 ”的 filter() 方 法 。 


]AX-RS 容 器 


5) 过 滤 处 理 完毕 后 ， 服 务 器 根据 请 求 匹配 资源 方法 ， 如 果 匹 配 到 相应 的 资源 方法 ， 流 程 进入 第 四 个 扩展 点 : “服务 器 后 置 请 求 过 滤器 ContainerRequestFilter 实 现 类 ”的 filter() 方 法 。 


6) 后 置 请 求 过 滤 处 理 完毕 后 ， 流 程 进入 第 五 个 扩展 点 : “服务 器 读 拦截 器 Readerlnterceptor 实 现 类 ”的 aroundReadFrom() 方 法 ， 拦 截 服务 器 端 反 序列 化 操作 。 


7) “服务 器 消息 体 读 处 理 器 MessageBodyReader” 完 成 对 客户 端 数据 流 的 反 序列 化 。 服 务 器 执行 匹配 的 资源 方法 。 


8) REST 请 求 资源 的 处 理 完毕 后 ， 流 程 进入 第 六 个 扩展 点 : “服务 器 响应 过 滤器 ContainerResponseFilter 实 现 类 ”的 filter() 方 法 。 


9) 过 滤 处 理 完毕 后 ， 流 程 进入 第 七 个 扩展 点 : “服务 器 写 拦截 器 Writerlnterceptor 实 现 类 ”的 aroundWriteTo() 方 法 ， 实 现 对 服务 器 端 序列 化 到 客户 端 这 个 操作 的 拦截 。 


10) “服务 器 消息 体 写 处 理 器 MessageBodyWriter” 执 行 序列 化 ， 流 程 返回 到 客户 端 一 侧 。 


11) 客户 端 接 收 响应 ， 流 程 进入 第 八 个 扩展 点 : “客户 端 响应 过 滤器 ClientResponseFiltter 实 现 类 ”的 filter() 方 法 。 


12) 过 滤 处 理 完毕 后 ， 客 户 端 响应 实例 response 返 
法 ， 对 客户 端 反 序列 化 进行 拦截 。 


回 


到 用 户 一 出， 用 户 执行 response.readEntity()， 流 程 进入 第 九 个 扩展 点 : “客户 端 读 拦截 器 Readerlnterceptor 实 现 类 ” 的 aroundReadFrom() 方 


13) “客户 端 消 息 体 读 处 理 器 MessageBodyReader” 执 行 反 序列 化 ， 将 Java 类 型 的 对 象 最 终 作 为 readEntity() 方 法 的 返回 值 。 


到 此 ， 一 次 REST 请 求 处 理 的 完整 流程 完毕 。 在 这 个 期 间 ， 如 果 出 现 异 常 或 资源 不 匹配 等 情况 ， 则 会 从 出 错 点 结束 流程 。 


4.4 REST 过 滤器 


从 上 一 节 的 流程 讲述 中 ， 我 们 了 解 JAX-RS 2.0 定 义 的 4 种 过 滤器 扩展 点 (extension point) 接口 ， 供 开发 者 实现 业务 逻辑 ， 按 请 求 处 理 流 程 的 先后 顺序 为 : 客户 端 请 求 过 滤器 
ientRequestFilter) 一 服务 器 请 求 过 滤器 (ContainerRequestFilter) 一 服务 器 响应 过 滤器 (ContainerResponseFilter) 一 客户 端 响应 过 滤器 (ClientResponseFilter) 。 本 节 将 全 面 讲述 4 种 过 滤器 的 


4.4.1 ClientRequestFilter 


客户 端 请 求 过 滤器 (ClientRequestFilter) 定义 的 过 滤 方 法 fitter(0 包 含 一 个 输入 参数 ， 是 客户 端 请 求 的 上 下 文 类 ClientRequestContext。 从 该 上 下 文中 可 以 获取 请 求 信息 ， 典 型 的 示例 包括 获取 请 求 方 
法 context.getMethod(0， 获 取 请 求 资源 地 址 context.getUri0 和 获取 请 求 头 信息 context.getHeaders() 等 。 过 滤器 的 实现 类 中 可 以 利用 这 些 信息 ， 覆 写 该 方法 以 实现 该 类 特有 的 过 滤 功能 。 
ClientRequestFilter 接 口 的 实现 类 如 图 4-5 所 示 。 


public interface ClLiertRequestFilter { 


Choose Implementation of ClientRequestFilter (8 found) 


© AirClientRequestFilter (com.example.resource.filter) jaxrs2-handle C3 


Filter met| >» ,. ， ) 
@ AirLogFilter (com.example.filter.log) xrs2-handle 马 
k transport - = ~ re x = = > = 
@ csrfprotectionFilter (org.glassfishjersey.client,filter) Maven: org.glassfish,jersey.core:jersey-client:2,5 (Jersey-client-2.5,ar) 


外 EncodingFilter (org.glassfishjersey.client.filter) Maven: org.glassfish,jersey.core:jersey-client:2.5 (jersey-client-2.5jan [ 丽 


了 1 了 terS in 
y class-leve 图 HttpAuthenticationFilter (org.glassfishjersey.client.authentication) Maven: org.glas Jjersey.corejjersey-client:2.5 (ersey-client-2.5jan [ 邑 
外 HtPBasieAuthFiter (org.glassfish,jersey.client.filter) Maven: org.glassfish.jersey.core:jersey-client:2.5 (jersey-client-2.5jan [ 玉 
* eparam rd © HipDigestAuthFilter (org.glassfish.jersey.client.filter) Maven: org.glassfish.jersey.core:jersey-client:2.5 (jersey-client-2.5jan [8 


© LoggingFilter (org.glassfish.jersey.filter) Maven: org.glassfish.ersey.core:jersey-common:2.5 (jersey-common-2.5jan 国 


图 4-5 ”ClientRequestFilter 接 口 的 实现 类 


图 4-5 展 示 了 ClientRequestFilter 接 口 的 实现 类 ， 包 括 Jersey 内 部 提供 的 实现 类 和 本 书 示 例 代 码 中 的 实现 类 。 我 们 选择 HTTP 基 本 认证 过 滤器 类 HttpBasicAuthFilter 作 为 例子 ， 来 感受 上 面 的 讲述 (HTTP 
基本 认证 这 个 知识 点 可 参考 6.1 节 ) 。 示 例 代码 如 下 所 示 。 


QOverride 
public void filter 
(ClientRequestContext rc 
) throws IOException { 
生生 
(!rc.getHeaders () .containsKey 
(HttpHeaders .AUTHORIZATION 
}Y 4 


rc.getHeaders () .add 
(HttpHeaders .AUTHORIZATION, authentication 
); 


上 
} 


在 这 段 代 码 中 ，HTTP 基 本 认证 过 滤器 类 在 filter() 方 法 中 ， 判 断 请 求 头 信息 中 是 否 包含 “Authorization” ， 如 果 不 包 含 ， 则 添加 请 求 头 “Authorization” 为 authentication，authentication 的 内 容 
是 “Basic”+Base64.encodeAsString (usernamePassword) 。 这 样 以 来 ， 经 过 HTTP 基 本 认证 过 滤器 类 过 滤 处 理 后 ， 可 以 确保 请 求 头 信息 中 包含 “Authorization” 。 


QOverride 
public void filter 
(ClientRequestContext rc 
) throws IOException { 
站 
(!rc.getHeaders () .containsKey 
(HttpHeaders .AUTHORIZATION 
和 
rc.getHeaders () .add 
(HttpHeaders .AUTHORIZATION, authentication 
); 
} 
} 


44.2 ContainerRequestFilter 


针对 过 滤 切 面 ， 服 务 器 请 求 过 滤器 接口 ContainerRequestFiltter 的 实现 类 可 以 定义 为 预 处 理 和 后 处 理 。 默 认 情 况 下 ， 采 用 后 处 理 方式 ， 即 先 执行 容器 接收 请 求 操作 ， 当 服务 器 接收 并 处 理 请 求 后 ， 流 程 
才 进 入 过 滤器 实现 类 的 filter() 方 法 。 而 预 处 理 是 在 服务 器 处 理 接收 到 的 请 求 之 前 就 执行 过 滤 。 如 果 希 望 实现 一 个 预 处 理 的 过 滤器 实现 类 ， 需 要 在 类 名 上 定义 注解 @PreMatching。 


服务 器 请 求 过 滤器 定义 的 过 滤 方 法 filter() 包 含 一 个 输入 参数 ， 即 容器 请 求 上 下 文 类 ContainerRequestContext。ContainerRequestFilter 接 口 的 实现 类 如 图 4-6 所 示 。 


public interface ContainerRegquestFilter { 


taine , - te axrs2-handle 
@@ AirContainerRequestpreFilter (com.example.resource.filter) jaxrs2-handle C3 
@ AirDynamicBindingFilter (com.example.resource.bing) jaxrs2-handle C3 
@ AirLogFilter (com.example.filter,log) jaxrs2-handle C3 
@ AirNameBindingFilter (com.example.resource.bing) jaxrs2-handle C3 
@ AirNameBindingFilter2 (com.example.resource.bing) jaxrs2-handle C3 
@ CsrfprotecionFilter (org.glassfishjersey.server.filter) Maven: org.glassfish.jersey.core:jersey-server:2.5 (jersey-server-2.5jar) 图 
@ HtpMethodOverrideFilter (org.glassfishjersey.server,filter) Maven: org.glassfish.jersey.core:jersey-server:2,5 (jersey-server-2.5.jar) [® 
@ LoggingFilter (org.glassfishjersey.filter) Maven: org,glassfishjersey.corejersey-common:2.5 (jersey-common-2,5.jar) 国 
BD RolesAllowedRequestfFilter in RolesAllowedDynamicFeature (org.glassfish.jersey.server.filter) Maven: org.glassfishjersey.core:jersey-server:2.5 (jersey-server-2.5.jar) 力 


@ UriConnegFilter (org.glassfish.jersey.server.filter) Maven: org.glassfish.jersey.core:jersey-server:2,5 Uersey-server-2.5jar) [® 


图 4-6 ”ContainerRequestFilter 接 口 的 实现 类 


图 4-6 展 示 了 ContainerRequestFilter 接 口 的 实现 类 ， 我 们 以 CsrfProtectionFilter 为 例 来 说 明 (CSRF 这 个 知识 点 可 参考 6.5 节 ) 。 示 例 代码 如 下 所 示 。 


QPriority 
(Priorities.AUTHENTICATION 
) 


Public class CsrfProtectionFilter implements ContainerRequestFilter { 
Pa static final String HEADER NAMP = "X-Requested-By"; 


ET 
忽略 方法 集合 
private static final Set<String> METHODS TO IGNORE; 
static { 
HashSet<String> mti = new HashSet<String> () 7 
mti.add 
("GET" 
} 
mti.add 
("OPTIONS" 
); 
mti.add 
("HERAD" 
) 
METHODS_TO_IGNORE = Collections.unmodifiableSet 
(mti 
} 
QOverride 
public void filter 
(ContainerRequestContext rc 
) throws IOException { 
wr 


关注 点 2 
人 符合 条 件 


Cio TO_IGNORE .contains 
ee getMethod () 


&& !rc.getHeaders () .containsKey 
(HEADER NAME. 
>) 1 


throw new BadRequestException(); 
} 


在 这 段 代 码 中 ，CsrfProtectionFilter 定 义 了 一 个 特殊 的 头 信息 “X-Requested-By” 和 CSRF 忽 略 监控 的 方法 集合 ， 见 关注 点 1。 在 过 滤器 的 filter() 方 法 中 ， 首 先 从 上 下 文中 获取 头 信息 (使 用 
rc.getHeaders()) 和 请 求 方法 信息 (使 用 rc.getMethod0) ， 然 后 判断 头 信息 是 否 包含 “X-Requested-By” ， 方 法 信息 是 否 是 安全 的 请 求 方法 ， 即 “GET”、 “OPTIONS"” 或 “HEAD”。 如 果 两 个 条 件 
都 不 成 立 ， 那 么 过 滤器 会 抽出 一 个 运行 时 异常 BadRequestException， 见 关注 点 2。 


通过 CsrfProtectionFilter 过 滤器 ， 可 以 确保 请 求 是 CSRF 安 全 的 。 


宅 人 坑 事 


CsrfProtectionFilter 类 使 用 了 注解 @Priority (Priorities.AUTHENTICATION) 来 定义 该 类 ， 明 确 了 该 过 滤器 具有 最 高 的 优先 级 。 同 时 ， 以 注解 的 文字 告诉 开发 者 ， 需 要 将 其 放 在 过 滤器 链 的 第 一 个 位 置 。 因 
此 ， 在 定义 和 使 用 过 滤器 时 ， 需 要 考虑 运行 时 中 过 滤器 的 执行 先后 顺序 ， 否 则 无 法 实现 过 滤器 的 功能 或 者 使 流程 混乱 。 


4.4.3 ContainerResponseFilter 


服务 器 响应 过 滤器 接口 ContainerResponseFilter 定 义 的 过 滤 方 法 filter( 包 含 两 个 输入 参数 ， 一 个 是 容器 请 求 上 下 文 类 ContainerRequestContext， 另 一 个 是 容器 响应 上 下 文 类 
ContainerResponseContext。ContainerResponseFilter 接 口 的 实现 类 如 图 4-7 所 示 。 


public interface ContainerResponseFilter { 

G@ AirContainerResponseFilter (com.example.resource.filter) jaxrs2-handle 

© AirLogFilter (com.example.filter.log) jaxrs2-handle C3 
| @ AirNameBindingFilter (com.example.resource.bing) jaxrs2-handle 加 
+ @ AirNameBindingFilter2 (com.example.resource.bing) jaxrs2-handle 也 
* Filters i ® EncodingFilter (org.glassfishjersey.server.filter) Maven: org.glassfishjersey.core:jersey-server:2.5 (jersey-server-2.5jan [® 


/x 
Filter met| 
* (either byl 


* clsass-level 图 LoggingFilter (org.glassfish.jersey.filter) Maven: org.glassfish,jersey.core:jersey-common:2.5 (ersey-common-2.5jan [®® 


图 4-7 ContainerResponseFilter 接 口 的 实现 类 


图 4-8 展 示 了 ContainerResponseFilter 接 口 的 实现 类 ， 我 们 以 EncodingFilter 为 例 来 说 明 。 该 过 滤器 的 作用 是 完成 内 容 协商 中 编码 匹配 的 工作 (内容 协商 这 个 知识 点 可 参考 3.6 节 ) ， 示 例 代 码 如 下 所 


QPriority (Priorities.HEADER DECORATOR) 

public final class EncodingFilter implements ContainerResponseFilter { 
QOverride 
public void filter (ContainerRequestContext request, 
ContainerResponseContext response) throws IOException { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


List<String> varyHeader = 
( (ContainerResponse) response) .getStringHeaders () .get (HttpHeaders.VARY); 


// 

关注 点 1 

: Vary 

头 信息 
if (varyHeader == null || !varyHeader.contains (HttpHeaders.ACCEPT ENCODING)) { 

response.getHeaders () .add (HttpHeaders .VARY, HttpHeaders.ACCEPT ENCODING); 

} 
if (response.getHeaders () .getFirst (HttpHeaders.CONTENT ENCODING) != null) { 


return; 
} 
List<String> acceptEncoding = request .getHeaders () 
.get (HttpHeaders .ACCEPT ENCODING); 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


ue 
关注 点 1 
: Content-Encoding 
头 信息 
if (!IDENTITY ENCODING.equals (contentEncoding)) { 
response.getHeaders () .putSingle (HttpHeaders .CONTENT ENCODING, contentEncoding); 


} 


EncodingFilter 过 滤器 的 filter() 方 法 通过 对 请 求 头 信息 “Accept-Encoding” 的 分 析 ， 先 后 为 响应 头 信息 “Vary” 和 “Content-Encoding” 赋 值 ， 以 实现 编码 部 分 的 内 容 协商 ， 见 关注 点 1。 


4.4.4 ClientResponseFilter 


客户 端 响应 过 滤器 ClientResponseFilter 定 义 的 过 滤 方 法 filter( 包 含 两 个 输入 参数 ， 一 个 是 客户 端 请 求 的 上 下 文 类 ClientRequestContext， 另 一 个 是 客户 端 响应 的 上 下 文 类 ClientResponseContext。 
ClientResponseFilter 接 口 的 实现 类 如 图 4-8 所 示 。 


public interface ClientResponseFilter { 


/好 es 
@ AirClientResponseFilter (com.example.resource.filter) 
* Filter met| ~ ,. 本 

AirLogFilter (com.example.filter.log) 
(either byl 


HITP invod 


Filters in 


图 4-8 ”ClientResponseFilter 接 口 的 实现 类 


区 


知识 点 可 参考 6.1 节 ) 。 示 例 代码 如 下 所 示 。 


Choose Implementation of ClientResponseFilter (5 found) 


jaxrs2-handle 


jaxrs2-handle 


HttpAuthenticationFilter (org.glassfish.jersey.client.authentication) Maven: org.glassfish.jersey. 


© HtpBDrgesthuthHlter (org.glassfish,jersey.client.filter) Maven: org.glassfish.jersey. 


) LoggingFilter (org.glassfish,jersey.filter) 


4-8 展 示 了 ClientResponseFilter 接 口 的 实现 类 ， 包 括 Jersey 内 部 提供 的 实现 类 和 本 书 示例 代码 中 的 实现 类 。 我 们 以 HTTP 搞 要 认证 过 滤器 类 HttpDigestAuthFilter 为 例 进行 演示 (HTTP 摘 要 认证 这 个 


QOverride 


public void filter (ClientRequestContext requestContext, ClientResponseContext responseContext) throws IOException { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


if (Response.Status.fromStatusCode (responseContext .getStatus () ) 
== Status.UNAUTHORIZED) { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


Client client = requestContext.getClient (); 
String method = requestContext .getMethod(); 
MediaType mediaType = requestContext .getMediaType(); 
URI 1lUri = requestContext .getUri () 7 
WebTarget resourceTarget = client.target (1lUri); 
Invocation.Builder builder = resourceTarget .request (mediaType); 
builder.headers (requestContext .getHeaders ()); 
// 

关注 点 1 

: 增加 "WWW-Authenticate" 

头 信息 
builder.header (HEADER DIGEST SCHEME, digestScheme); 
Invocation invocation = builder.build (method); 


新 发 送 一 次 携带 "WWW-Authenticate" 


息 的 请 求 
Response nextResponse = invocation.invoke(); 
if (nextResponse == null) { 
return; 
if (nextResponse.hasEntity()) { 


responseContext .setEntityStream (nextResponse.readEntity (InputStream.class)); 
MultivaluedMap<String, String> headers = responseContext .getHeaders(); 
headers.clear (); 
headers .putAll (nextResponse.getStringHeaders () ) 7 
responseContext .setStatus (nextResponse.getStatus () ) 7 


息 “WWW-Authenticate”， 见 关注 点 1。 如 果 “WWW-Authenticate” 信 息 存 在 ， 则 会 自动 重新 发 送 一 次 携带 该 信息 的 请 求 ， 


在 这 段 代码 中 ，HttpDigestAuthFilter 的 filter() 方 法 校 验 响应 信息 ， 如 果 服 务 器 的 响应 信息 中 ，HTTP 状 态 码 是 UNAUTHORIZED (401，“Unauthorized”) ， 该 过 滤器 会 尝试 添加 摘要 认证 的 头 信 


在 “WWW-Authenticate” 头 信息 ， 可 以 简化 手动 交互 的 过 程 。 


4.4.5 ”访问 日 志 


见 关注 点 2。 这 样 以 来 ， 经 过 HTTP 摘 要 认证 过 滤器 类 过 滤 处 理 后 ， 如 果 存 


4.4.1~4.4.4 节 完成 了 对 JAX-RS 2.0 定 义 的 4 种 过 滤器 的 讲述 ， 本 小 节 利 用 上 述 知 识 ， 演 示 如 何 综合 运用 过 滤器 ， 完 成 一 个 记录 REST 请 求 的 访问 日 志 。 


1. 访 问 日 志 实现 类 


访问 日 志 类 AirLogFilter 实 现 了 上 述 的 4 种 过 滤器 ， 旨 在 记录 服务 器 和 客户 端的 请 求 和 响应 中 的 运行 时 信息 。AirLogFilter 类 定义 如 下 所 示 。 


@PreMatching 
public class AirLogFilter implements ContainerRequestFilter, ClientRequestFilter, 


ContainerResponseFilter, ClientResponseFilter { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 


AirLogFilter 为 每 一 种 过 滤器 接口 定义 的 filter0 方 法 提供 了 实现 。 在 客户 端 请 求 过 滤 中 ， 输 出 请 求 资源 地 址 信息 和 请 求 头 信息 ;在 容器 请 求 过 滤 中 ， 输 出 请 求 方法 、 请 求 资源 地 址 信息 和 请 求 头 信息 ; 在 
容器 响应 过 滤 中 ， 输 出 HTTP 状 态 码 和 请 求 头 信息 ; 在 客户 端 响应 过 滤 中 ， 输 出 HTTP 状 态 码 和 请 求 头 信息 。4 个 阶段 的 filter 示 例 代码 如 下 所 示 。 


QOverride 

public void filter(ClientRequestContext context) throws IOException { 
long id = logSequence.incrementAndGet (); 
StringBuilder b = new StringBuilder () 7 


: 获取 请 求 方法 和 地 址 
printRequestLine (CLIENT REQUEST, b, id, context.getMethod(), context.getUri ()); 


取 请 求 头 信息 
printPrefixedHeaders (CLIENT REQUEST, b, id, 
HeadersFactory.asStringHeaders (context .getHeaders ())); 
LOGGER. info (b.toString()) 7 
} 


在 这 段 代码 中 ，Filter 类 实现 了 客户 端 请 求 过 滤 。 从 客户 端 请 求 上 下 文 实例 中 ， 可 以 获取 到 请 求 方法 和 请 求 地 址 信息 ， 见 关注 点 1。 同 样 ， 头 信息 也 可 以 从 中 获取 ， 见 关注 点 2。 


QOverride 
public void filter (ClientRequestContext requestContext, 
ClientResponseContext responseContext) throws IOException { 
long id = logSequence.incrementAndGet () 7 
StringBuilder b = new StringBuilder(); 


局 

: 获取 响应 状态 
printResponseLine (CLIENT RESPONSE, b, id, responseContext.getStatus()); 
// 


关注 点 2 

: 获取 响应 头 信息 
printPrefixedHeaders (CLIENT RESPONSE, b, id, responseContext .getHeaders () ) 
LOGGER.info (b.tostring()); 一 

} 


在 这 段 代码 中 ，Filter 类 实现 了 客户 端 响应 过 滤 。 从 客户 端 响应 上 下 文 实例 中 ， 可 以 获取 响应 状态 信息 和 响应 头 信息 ， 分 别 见 关注 点 1 和 关注 点 2。 


QOverride 
public void filter (ContainerRequestContext context) throws IOException { 
long id = logSequence.incrementAndGet () 7 
StringBuilder b = new StringBuilder ()7 
1 
关注 点 1 
: 获取 容器 请 求 方法 和 请 求 地 址 信息 
printRequestLine (SERVER REQUEST, b, id, context.getMethod!(), 
context .getUriInfo() .getRequestUri ()); 
Hi 


关注 点 2 

: 获取 请 求 头 信息 
printPrefixedHeaders (SERVER REQUEST, b, id, context.getHeaders()); 
LOGGER. info (b.toString())7 

} 


在 这 段 代码 中 ，Filter 类 实现 了 容器 请 求 过 滤 。 从 容器 请 求 上 下 文 实例 中 ， 可 以 获取 请 求 方法 和 请 求 资 源 地 址 信息 ， 见 关注 点 1。 同 样 ， 可 以 从 中 获取 请 求 头 信息 ， 见 关注 点 2。 


QOverride 
public void filter (ContainerRequestContext requestContext, 
ContainerResponseContext responseContext) throws IOException { 
long id = logSequence.incrementAndGet (); 
StringBuilder b = new StringBuilder () 7 


> 器 响应 状态 
printResponseLine (SERVER RESPONSE, b, id, responseContext.getStatus()); 


: 慑 器 响应 头 信息 
printPrefixedHeaders (SERVER RESPONSE, i 
HeadersFactory.asStringHeaders (responseContext .getHeaders ())); 
LOGGER. info (b.toString ()) 7 


在 这 段 代 码 中 ，Filter 类 实现 了 容器 响应 过 滤 。 从 容器 响应 上 下 文 实例 中 ， 可 以 获取 容器 的 响应 状态 信息 和 响应 头 信息 ， 见 关注 点 1 和 关注 点 2。 


2. 单 元 测试 类 


访问 日 志 的 单元 测试 示例 如 下 所 示 。 


public class TIResourceJtfTest extends JerseyTest { 
QOverride 
protected Application configure() { 
ResourceConfig config = new ResourceConfig 
(BookResource.class 
); 
return config.register 
(com.example.filter.log.AirLogFilter.class 
); 
} 
QOverride 
protected void configureClient 
(ClientConfig config 
了 
config.register 
(new AirLogFilter () 
yy 
} 


在 这 段 代 码 中 ， 为 了 使 访问 日 志 类 生效 ， 需 要 测试 类 TIResourcejtfTest 在 Jersey 测 试 框架 的 服务 器 端 和 客户 端 ， 分 别 注册 服务 日 志 类 AirLogFilter。 


单元 测试 的 结果 如 下 所 示 ， 在 4 种 过 滤器 中 分 别 打印 了 该 阶段 的 日 志 信 息 。 


main -~ 1 * RirLog - Request received on thread main 

1 / GET http://localhost:9998/books/1 

1 / Accept: application/json 

Grizzly-worker 

人 王 

) - 2 * RirLog - Request received on thread Grizzly-worker 


(1 


) 
2 > GET http://localhost:9998/books/1 
2 > accept: application/json 


Grizzly-worker 
( 


) - 3 * AirLog - Response received on thread Grizzly-worker 


) 
多 
3 < Content-Type: application/json 

main -~ 4 * AirLog - Response received on thread main 
4 \ 200 

4 


\ Content-Type: application/json 


4.5” REST 拦截 器 


拦截 器 和 过 滤器 的 相同 之 处 在 于 都 是 一 种 在 请 求 一 响应 模型 中 用 做 切面 处 理 的 Provider。 两 者 的 不 同 除了 功能 上 的 差异 (一 个 用 于 过 滤 消 息 ， 另 一 个 用 于 拦截 处 理 ) 之 外 ， 形 式 上 也 不 同 。 拦 截 器 通常 
读 写成 对 ， 而 且 没有 服务 器 端 和 客户 端的 区 分 。Jersey 提 供 的 拦截 器 类 如 图 4-9 所 示 。 


Choose Implementation of ReaderInterceptor 


< AirReaderInterceptor i 


© ContentEncoder (org.glassfish,jers 


Cc DefateEneoder orgahaesfphjereeynmes ge) 
9 GZipEncoder (org.glassfish,jersey.message) 
5 ee ey.server,internal) 


5) TerminalReaderInterceptor in ReaderInterceptorExecutor (org.glass 


LE. AirWriterInterceptor (com.example.resource.interceptor) 
生 ContentEncoder (org.glassfish.jersey.sp)) 

5 DeflateEncoder (org.glassfish.jersey.message) 

9 GZipEncoder (org.glassfish,jersey.message) 

S) JsonWithPaddingInterceptor (org.glassfish.jersey 

时 LoggingFilter (org.glassfish,jersey.filter) 


5 MappableExceptionWrapperinterceptor (org.glassfish,jersey.server.internal) 


SE) TerminalWriterInterceptor in WriterInterceptorExecutor (org.glassfish.jersey.message.internal) 


图 4-9 读 写 拦截 器 的 实现 类 


如 图 4-9 所 示 ，Jersey 内 部 实现 了 几 个 典型 应 用 的 拦截 器 ， 它 们 是 成 对 出 现 的 。 比 如 GZiPEncoder 同 时 实现 了 读 / 写 拦截 器 ， 以 实现 使 用 GZip 压 缩 格 式 压 缩 消息 体 的 功能 。 


(1) ReaderInterceptor 


读 拦截 器 接口 Readerlnterceptor 定 义 的 拦截 方法 是 aroundReadFrom()， 该 方法 包含 一 个 输入 参数 ， 即 读 拦截 器 的 上 下 文 接口 ReaderlnterceptorContext， 从 中 可 以 获取 头 信息 、 输 入 流 以 及 父 接 
InterceptorContext 提 供 的 媒体 类 型 等 上 下 文 信息 。 接 口 方法 示例 如 下 。 


Public Object aroundReadFrom 
(ReaderInterceptorContext context 
) throws 
java.io.IOException, javax.ws.rs.WebApplicationException; 


(2) WriterInterceptor 


写 拦截 器 接口 Writerlnterceptor 定 义 的 拦截 方法 是 aroundWriteTo()， 该 方法 包含 一 个 输入 参数 ， 即 写 拦截 器 上 下 文 接口 WriterlnterceptorContext， 从 中 可 以 获取 头 信息 、 输 出 流 以 及 父 接 
InterceptorContext 提 供 的 媒体 类 型 等 上 下 文 信息 。 接 口 方法 示例 如 下 所 示 。 


Void aroundWriteTo (WriterIinterceptorContext context)throws 
java.io.IOException, javax.ws.rs.WebApplicationException; 


(3) 编 解码 约束 拦截 器 


编 解 码 约束 拦截 器 类 ContentEncoder 是 一 个 位 于 org.glassfish.jersey.spi 包 中 的 拦截 器 ，SPl 包 下 的 工具 是 可 插 拔 的 。ContentEncoder 拦 截 器 用 于 约束 序列 化 和 反 序 列 化 过 程 中 的 编 解码 的 内 容 协 商 ， 
示例 代码 如 下 所 示 。 


QOverride 
public final Object aroundReadFrom (ReaderInterceptorContext context) 
throws IOException, WebApplicationException { 

String contentEncoding = context .getHeaders () 

.getFirst (HttpHeaders. CONTENT ENCODING); 


context .setIinputStream (decode (contentEncoding, context.getInPutStream() ) ) 7 


拦截 链 的 下 一 个 拦截 处 理 


return context.proceed(); 


QOverride 
public final void aroundWriteTo (WriterInterceptorContext context) 
throws IOException, WebApplicationException { 
String contentEncoding = 
(String) context.getHeaders() .getFirst (HttpHeaders.CONTENT ENCODING); 
py 


局 4 
是 否 包含 content-Encoding 


(contentEncoding != null 

&& getSupportedEncodings () .contains (contentEncoding)){ 
关注 点 5 
: 编码 处 理 

context .setOutputStream (encode (contentEncoding, context.getOutputStream() ) ) 7 
} 
// 
6 


关注 点 


拦截 链 的 下 一 个 拦截 处 理 
context .proceed (); 


} 


在 这 段 代 码 中 ， 分 别 给 出 了 ContentEncoder 拦 截 器 的 读 、 写 拦截 处 理 ， 读 取 阶 段 进行 解码 ， 写 入 阶段 进行 编码 ， 分 别 见 关注 点 2 和 关注 点 5。 只 有 当头 信息 包含 “Content-Encoding” 信 息 时 ， 编 解码 
才 被 执行 ， 见 关注 点 1 和 关注 点 4。 上 下 文 的 proceed() 方 法 用 于 执行 拦截 器 链 的 下 一 个 拦截 器 ， 见 关注 点 3 和 关注 点 6。 


4.6 绑 定 机 制 


在 我 们 了 解 了 面向 切面 的 Providers 的 功能 后 ， 需 要 掌握 它们 是 如 何 加 载 的， 以 及 它们 的 作用 域 。 这 些 容器 级 别 的 Providers， 通 常 使 用 编码 的 方式 注册 到 Application 中 ， 但 这 不 是 唯一 的 办 法 。 本 节 将 
详细 讨论 Providers 的 绑 定 机 制 。 


默认 情况 下 ， 过 滤器 和 拦截 器 都 是 全 局 绑 定 的 ， 也 就 是 说， 下 列 其 中 之 一 的 过 滤器 或 拦截 器 是 全 局 有 效 的 : 


“ 通过 手动 注册 到 Application 或 者 Configuration。 


' 注解 为 @Provider， 被 自动 探测 。 


下 面 介 绍 其 他 的 绑 定 机 制 。 


1. 名 称 绑 定 


过 滤器 或 拦截 器 可 以 使 用 特定 的 注解 来 指定 其 作用 范围 ， 这 种 特定 的 注解 称 为 名 称 绑 定 。 


ez 


(1) 名 称 绑 定 注解 


使 用 @NameBinding 注 解 可 以 定义 一 个 运行 时 的 自 定义 注解 ， 该 注解 用 于 定义 类 级 别名 称 和 类 的 方法 名 ， 示 例 代码 如 下 所 示 。 


@NameBinding 

QTarget 

({ ElementType.TYPE, ElementType.METHOD } 
) 

@Retention 

(value = RetentionPolicy .RUNTIME 

) 

public Qinterface AirLog { 

i 


在 这 段 代码 中 ， 自 定义 注解 AirLog 使 用 了 @NameBinding， 在 运行 时 该 注解 将 解析 为 一 个 名 称 绑 定 的 注解 。 


(2) 绑 定 Provider 


在 定义 了 @AirLog 注 解 后 ， 即 可 在 Provider 中 使 用 该 注解 ， 示 例 代码 如 下 所 示 。 


uf 
关注 点 1 
: 使 用 自 定义 注解 6AirLog 
@AirLog 
@Priority (Priorities .USER) 
public class AirNameBindingFilter implements ContainerRequestrFilter, 
ContainerResponseFilter { 
private static final Logger LOGGER = Logger.getLogger (AirNameBindingFilter.class); 
public AirNameBindingFilter() { 
LOGGER. info ("Air-NameBinding-Filter initialized"); 
} 
QOverride 
a 
关注 点 2 
: filter 
实现 访问 日 志 
public void filter (final ContainerRequestContext containerRequest) 
throws IOException { 
LOGGER. debug ("Air-NameBinding-ContainerRequestFilter invoked:" + 
containerRequest .getMethod()); 
LOGGER. debug (containerRequest .getUriInfo() .getRequestUri ()); 


} 
QOverride 
// 

点 3 


+ er 
实现 访问 日 志 
public void filter (ContainerRequestContext containerRequest, 
ContainerResponseContext responseContext) throws IOException { 
LOGGER. debug ("Air-NameBinding-ContainerResponseFilter invoked:" + 
containerRequest .getMethod()); 
LOGGER.debug ("status=" + responseContext .getStatus()); 


在 这 段 代 码 中 ， 过 滤器 类 AirNameBindingFilter 使 用 了 自 定义 注解 @AirLog， 这 样 Air-NameBindingFilter 类 就 实现 了 名 称 绑 定 ， 见 关注 点 1。 该 类 实现 了 容器 的 请 求 和 响应 过 滤器 接口 ， 功 能 是 记录 访 


问 日 志 ， 见 关注 点 2 和 关注 点 3。 


(3) 绑 定 方法 


接 下 来 ， 我 们 在 资源 方法 级 别 使 用 自 定 义 注 解 @AirLog， 来 实现 在 资源 类 的 指定 方法 上 启用 AirNameBindingFilter 过 滤器 ， 示 例 代 码 如 下 所 示 。 


Q@Path ("books") 
Public class BookResource { 


关注 点 1 

: 绑 定 方法 

@AirLog 
QGET 
QProduces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Books getBooks() { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


return books; 


} 
Q@Path (" {bookId: [0-9]*}") 
@GET 
QProduces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Book getBookByPath (@PathParam("bookId") final Long bookId) { 
final Book book = BookResource.memoryBase.get (bookId); 
return book; 


在 这 段 代 码 中 ， 资 源 类 BookResource 包 含 多 个 方法 ， 我 们 只 在 getBooks() 方 法 上 使 用 了 注解 @AirLog， 而 其 他 方法 并 没有 绑 定 ， 见 关注 点 1。 


(4) 单元 测试 类 


接 下 来 ， 通 过 单元 测试 来 校 验 名 称 绑 定 的 设计 和 实现 是 否 正确 ， 示 例 代 码 如 下 所 示 。 


public class TestNamingBinding extends JerseyTest { 
Override 
protected Application configure () { 
Ef 
关注 点 1 
rAopConfig 
内 部 注册 了 AirNameBindingFilter 
return new AirAopConfig(); 


Public void testPathGetJSON() { 
final WebTarget pathTarget = target (BASE URI) .path("1"); 
final Invocation.Builder invocationBuilder = 
pathTarget .request (MediaType .APPLICATION JSON TYPE); 
final Book result = invocationBuilder.get (Book.class); 
Assert .assertNotNull (result .getBookId()); 


public void testGetAll() { 
final Invocation.Builder invocationBuilder = target (BASE URI) .request () 7 
final Books result = invocationBuilder.get (Books.class); 
Assert .assertNotNull (result .getBookList ()); 


在 这 段 代 码 中 ， 测 试 类 TestNamingBinding 通 过 AirAopConfig(0 注 册 了 AirNameBindingFilter 过 滤器 ， 见 关注 点 1。 该 类 包含 两 个 测试 方法 ， 分 别 测 试 资 源 类 BookResource 的 getBook ByPath0 和 


getBooks() 方 法 ， 分 别 见 关注 点 2 和 关注 点 3。 


我 们 可 以 从 终端 打印 的 信息 来 检验 名 称 绑 定 的 运行 结果 ， 示 例如 下 。 


Air-NameBinding-ContainerRequestFilter invoked:GET 
http://localhost:9998/books/ 
Air-NameBinding-ContainerResponseFilter invoked:GET 
status=200 


从 上 述 测试 结果 中 可 以 看 到 ， 只 有 在 testGetAII0 方 法 输出 的 日 志 中 输出 了 AirNameBindingFilter 类 中 定义 的 日 志 信 息 。 这 和 预期 的 “只 有 使 用 注解 @AirLog 定 义 的 方法 ， 才 会 在 请 求 流程 中 启用 相应 的 


Provider” 一 致 。 


名 称 绑 定 需要 通过 自 定义 的 注解 名 称 来 绑 定 Provider 和 扩展 点 方法 或 者 类 ， 相 比 而 言 ， 动 态 绑 定 无 须 新 增 注解 ， 而 是 使 
扩展 点 方法 的 名 称 、 请 求 方法 类 型 等 匹配 信息 。 在 运行 期 ， 一 旦 Provider 匹 配 当前 处 理 类 或 方法 ， 面 向 切面 的 Provider 方 法 


(1) 定义 绑 定 Provider 


AirDynamicFeature 类 实现 了 DynamicFeature 接 口 ， 示 例 代 码 如 下 。 


编码 的 方式 ， 实 现 动态 特征 接 


被 触发 。 


ljavax.ws.rs.container.DynamicFeature, 定义 


public class AirDynamicFeature implements DynamicFeature { 
QOverride 
public void configure (final ResourceInfo resourceInfo, final FeatureContext context) { 
boolean classMatched = 
BookResource.class.isAssignableFrom (resourceInfo.getResourceClass ()); 
boolean methodNameMatched = 
resourceInfo.getResourceMethod() .getName () .contains ("getBookBy"); 
boolean methodTypeMatched = 
resourceInfo.getResourceMethod() .isAnnotationPresent (POST.class); 
// 
关注 点 1 
: 匹配 成 功 才 注册 AirDynamicBindingFilter 
if (classMatched && (methodNameMatched | | methodTypeMatched)) { 
context .register (AirDynamicBindingFilter.class); 
} 
} 


public class AirDynamicBindingFilter implements ContainerRequestFilter { 
QOverride 


public void filter(final ContainerRequestContext requestContext) throws IOException { 
AirDynamicBindingFilter.LOGGER.debug ("Air-Dynamic-Binding-Filter invoked"); 
} 


在 这 段 代 码 中 ， 在 AirDynamicFeature 的 配置 方法 中 ， 启 用 了 如 下 匹配 规则 。 


' 类 匹配 : 对 BookResource 类 及 其 子 类 的 匹配 。 
“ 方法 名 称 匹 配 : 方法 名 包含 getBookBy 的 匹配 。 
“ 请 求 方法 类 型 匹配 : 与 POST 方法 的 匹配 。 


只 有 当 匹 配 成 功 时 ， 才 会 注册 AirDynamicBindingFilter。 对 于 Provider 的 实现 类 ， 并 没有 特殊 的 要 求 。 


(2) 单元 测试 类 


测试 类 TestDynamicBinding 注 册 了 动态 绑 定 特征 实现 类 AirDynamicFeature， 示 例 代 码 如 下 所 示 。 


public class TestDynamicBinding extends JerseyTest { 
QOverride 
protected Application configure() { 
ResourceConfig config = new ResourceConfig (BookResource.class); 
config.register (AMrDynamicFeature.class); 
return config; 
} 
QTest 
public void testPost() { 
final Book newBook = new Book ("Java Restful Web Service 
使 用 指南 -" + System.nanoTime ()); 
final Entity<Book> bookEntity = 
Entity.entity (newBook, MediaType.APPLICATION JSON TYPE); 
final Book savedBook =target (BASE URI) .request (MediaType .APPLICATION JSON TYPE) 
.Post (bookEntity, Book.class); a 
Assert .assertNotNull (savedBook.getBookId()); 


运行 测试 方法 ，AirDynamicBindingFilter 的 日 志 信 息 如 预期 输出 ， 示 例 代 码 如 下 所 示 。 


Air-Dynamic-Binding-Filter initialized 
Air-Dynamic-Binding-Filter invoked 


4.7 优先 级 


不 同 扩展 点 的 Provider 在 请 求 处 理 流程 中 的 顺序 在 4.3 节 已 经 阐述 ， 对 于 同一 个 扩展 点 的 多 个 Provider 的 执行 先后 顺序 是 靠 优 先 级 排序 的 。 


优先 级 的 定义 使 用 注解 @Priority， 优 先 级 的 值 是 一 个 整 型 值 ， 常 量 定义 在 javax.ws.rs.Priorities 类 中 。 对 于 ContainerRequest、PreMatchContainerRedquest、ClientRedquest 和 读 写 拦截 器 ， 该 数值 
采用 升序 策略 ， 即 数值 越 小 ， 优 先 级 越 高 ; 对 于 ContainerResponse 和 ClientResponse， 该 数值 采用 降序 策略 ， 即 数值 越 大 ， 优 先 级 越 高 。 示 例 代 码 如 下 所 示 。 


@Priority 

(Priorities.USER 

) 

public class AirNameBindingFilter 
@Priority 

(Priorities.USER + 1 

) 

public class AirNameBindingFilter2 


在 这 段 代 码 中 ，AirNameBindingFilter2 的 Priority 数 值 大 于 AirNameBindingFilter， 在 请 求 过 程 中 ，AirNameBindingFilter 优 先 执行 ， 而 在 响应 过 程 中 ，AirNameBindingFilter2 优 先 执行 。 


mh 


元 测试 代码 如 下 所 示 。 


public class TestPriority extends JerseyTest { 
QOverride 
protected Application configure() { 
ResourceConfig config = new ResourceConfig 
(BookResource.class 
); 
config.register 
(AirNameBindingFilter.class 
); 
config.register 
(AirNameBindingFilter2.class 
) 7 
return config; 
} 
QTest 
Public void testGetAll() { 
final Invocation.Builder invocationBuilder = target 
(BASE URI 
) .request (); 
final Books result = invocationBuilder.get 
(Books.class 
让 
Assert .assertNotNull 
(result .getBookList () 
| 
} 
} 


单元 测试 结果 如 下 所 示 ， 在 处 理 请 求 阶段 ，AirNameBindingFilter2 执 行 在 后 ; 在 响应 阶段 ，AirNameBindingFilter2 执 行 在 先 。 


Air-NameBinding-ContainerRequestFilter invoked:GET 
http://localhost:9998/books/ 
Air-NameBinding-ContainerRequestFilter2 Priority+1 invoked 
Air-NameBinding-ContainerResponseFilter2 Priority+1 invoked 
Air-NameBinding-ContainerResponseFilter invoked:GET 
status=200 


4.8 本章 小 结 


本 章 详 述 了 JAX-RS 2.0 定 义 的 Provider 及 其 两 个 特殊 类 型 : 过 滤器 和 拦截 器 ， 并 详细 讲述 了 JAX-RS 2.0 对 REST 请 求 的 处 理 过 程 中 各 个 扩展 点 对 应 的 Provider。 随 后 讲述 了 Provider 的 绑 定 机 制 和 优先 级 
机 制 。 下 一 章 ， 我 们 开始 介绍 REST 的 客户 端 。 


第 5 章 REST 客 户 端 


在 Java API for RESTful Web Services (JAX-RS) 1.x 的 定义 中 ， 没 有 关于 REST 客 户 端的 定义 。 但 是 ， 为 了 方便 开发 者 使 用 ，JAX-Rs 的 多 个 实现 项 目 (包括 Jersey、CXF 等 ) 都 自行 弥补 了 REST 客 户 端 
的 实现 。Jersey 1.x 的 客户 端 实现 底层 采用 的 是 Apache Http Client。JAX-RS 2.0 标 准 化 了 Client API (客户 端 API) 。Jersey 2.x 的 客户 端 包 jersey-client 实 现 了 JAX-RS 2.0 的 客户 端 AP1， 并 对 其 进行 了 可 插 
拔 的 〈pluggable) 扩展 。 客 户 端 API 通 过 HTTP 请 求 Web 资 源 ， 其 设计 宗旨 是 使 客户 端 API 符 合 统一 接口 和 REST 架 构 风 格 ， 同 时 客户 端 API 应 该 易于 使 用 ， 而 且 服 务 器 端 在 概念 和 扩展 点 上 保持 一 致 。 与 
Apache HTTP Client 和 HttpURLConnection 相 比 ， 客 户 端 API 是 具备 对 REST 的 感知 的 高 层 API， 可 以 和 Providers 集 成 ， 返 回 值 直接 对 应 高 层 的 业务 类 实例 ， 而 不 是 JAXB 对 象 或 者 更 为 低层 的 数据 类 型 。 


有 关 REST 客 户 端 的 实例 贯穿 每 一 章 的 实例 中 。 因 为 本 书 提倡 单元 测试 ， 所 以 每 个 实例 中 的 单元 测试 皆 使 用 了 REST 客 户 端 。 比 如 有 关 安 全 性 的 客户 端 实 例 可 以 参考 相关 章节 的 代码 ， 本 章 实 例 主 要 针对 通 
接口 和 连接 器 实践 。 


全 到 寺 提 南 本 章 示例 所 在 目录 是 jax-rs2-guide\sample\5\jaxrs2-client。 


源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/5/jaxrs2-client。 


5.1 ”客户 端 接口 
REST 客 户 端 主要 包括 三 个 接口 : javax.ws.rs.client.Client、javax.ws.rs.client.WebTarget 和 和 javax.ws.rs.client.Invocation。 接 下 来 我 们 逐一 讲述 。 


5.1.1 Client 接口 


Client 接 口 是 REST 客 户 端的 基本 接口 ， 用 于 和 REST 服 务 器 通信 。Client 被 定义 为 一 种 重量 级 的 对 象 ， 其 内 部 要 管理 客 
中 产生 大 量 的 Client 实 例 ， 这 一 点 需要 开发 者 注意 。 为 了 提示 读者 注意 ， 摘 出 源 代码 中 的 注释 如 下 。 


呈 
了 路 
型 


屋 实现 所 需 的 各 种 对 象 ， 比 如 连接 器 、 解 析 器 等 。 因 此 ， 不 推荐 在 应 


It is therefore advised to construct only a small number of Cleintinstances in the application. 


这 句 话 的 意思 是 在 应 用 中 尽量 少 地 构造 Client 实 例 。 另 外 ， 该 接口 要 求 其 实例 要 有 关闭 连接 的 保障 ， 否 则 会 造成 内 存 泄漏 。 


Jersey 对 JAX-RS 2.0 的 Client 接 口 的 实现 类 是 org.glassfish.jersey.client.JerseyClient。 创 建 一 个 Client 实 例 是 通过 ClientBuilder 构 造 的 ， 通 常 使 用 一 个 ClientConfig 实 例 作 为 参数 ， 该 实例 的 构建 过 程 
是 23 种 设计 模式 中 构造 模式 的 实践 。 在 传 入 ClientConfig 实 例 前 ， 通 常会 注册 (register) 相关 的 Provider 和 Feature， 也 可 以 设 定 自 定 义 属性 ( 键 值 对 ) ， 但 这 些 编码 都 是 可 选 的 。 最 简单 的 形式 是 没有 参 
数 的 构造 ， 示 例如 下 。 


Client client = ClientBuilder.newClient (); 


通常 情况 下 ， 在 客户 端 需要 加 载 指定 的 资源 、 注 册 某 些 Provider 或 者 预定 义 某 些 属性 ， 以 支持 更 复杂 的 业务 逻辑 。 我 们 在 ClientConfig 实 例 中 完成 了 这 些 配 置 后 ,将 
例 代 码 如 下 。 


作为 参数 在 Client 构 建 时 传 入 ， 示 


ClientConfig clientConfig = new ClientConfig(); 
clientConfig.register 
(MyProvider.class 

;// 


关注 点 1 
: 注册 Provider 
clientConfig. register 
(MyFeature.class 
i// 


关注 点 2 

: 注册 Feature 

clientConfig. register 

(new AnotherClientFilter() 

a 

关注 点 3 

: 注册 Filter 

Client client = ClientBuilder.newClient 
(clientConfig 


client .Property 
("MyProperty", "MyValue" 
a 

关注 点 4 

: 注册 属性 


在 这 段 代码 中 ， 在 构造 Client 实 例 前 ， 预 先 配 置 了 ClientConfig 实 例 ， 见 关注 点 1~ 关 注 点 3。 在 Client 实 例 中 ， 通 过 property() 方 法 同样 可 以 配置 相关 的 属性 ， 见 关注 点 4。 


在 配置 完毕 后 ， 可 以 通过 Client 的 getConfiguration() 方 法 获取 当前 Client 实 例 的 配置 信息 ， 示 例 代码 如 下 。 


Private void checkConfig() { 
Configuration newConfiguration = client.getConfiguration();// 
关注 点 1 
: 获取 client 
配置 


Map<String, Object> properties = newConfiguration.getProperties();// 


关注 点 2 
: 获取 配置 属性 
Iterator<Entry<String，Object>> iterator = properties .entrySet () .iterator (); 
while 
(iterator.hasNext () 
) {// 
关注 点 3 
: 友 代 属性 
Entry<String，Object> next = iterator.next (); 
LOGGER.debug 
(next.getKey() + ":" + next.getValue () 


在 这 段 代码 中 ， 在 关注 点 1 处 获取 了 client 配 


， 该 配置 包含 了 当前 客户 端 实例 的 


属性 键 值 对 信息 ， 见 关注 点 2。 通 过 和 迭代 该 键 值 对 可 以 获取 全 部 的 


属性 信息 ， 见 关注 点 3。 


Client 接 


口 还 提供 了 对 客户 端的 安全 连接 和 异步 的 支持 。 为 了 不 


5.1.2 WebTarget 接 口 


WebTarget 接 


是 为 REST 客 户 端 实现 资源 定位 的 接口 。 
org.glassfish.jersey.client.JerseyWebTarget。 


通过 WebTarget 接 


WebTarget 对 象 接收 配置 参数 的 方法 定义 有 很 浓厚 的 DSL (Domain Specific Language) 


， 可 以 定义 请 求 资源 的 


一 行 ， 而 是 要 分 开 来 写 ， 需 要 知道 WebTarget 接 口 所 采 
(该 方法 返回 的 是 this) 那样 设置 WebTarget 对 象 ， 而 是 必须 接收 设置 方法 的 返 


回 


如 下 做 法 是 不 合适 的 ，WebTarget 初 始 化 一 行 后 面 的 方法 调 


并 不 对 该 WebTarget 实 例 产 和 


体 地 址 、 


和 E 复 讲述 ， 可 参见 本 书 第 6 章 和 第 8 章 的 相关 内 容 。 


口 的 实现 类 是 


查询 参数 和 媒体 类 型 等 信息 。Jersey 对 JAX-RS 2.0 的 WebTarget 接 


“味道 ”， 通 过 方法 链 明 


可 完成 对 一 个 WebTarget 实 例 的 配置 。 但 是 ， 值 得 注意 的 是 ， 如 果 不 将 方法 链 写 成 


的 方法 链 模式 是 一 个 不 变 式 (immutable) 。 也 就 是 说 ， 其 返 
值 ， 作 为 后 续 流程 的 句柄 。 


作用。 


回 


值 是 一 个 新 的 WebTarget 对 象 ， 我 们 无 法 像 使 用 StringBuilder 的 append() 方 法 


WebTarget webTarget = client.target 
(BASE URI 
让 人， 


webTarget .path 
("books" 
yA 

关注 点 1 

: 设置 的 返回 值 被 丢弃 了 
webTarget .path 
("book" 

); 

webTarget .queryParam 
("pookId", "1" 

3 ， 


final Invocation.Builder invocationBuilder = webTarget.request 
(MediaType.APPLICATION XML 
| 加 


http://localhost:9527/client/ 


在 这 段 代码 中 ，WebTarget 实 例 每 次 设置 都 将 产生 一 个 新 的 WebTarget 实 例 ， 但 不 幸 的 是 ,该 实例 在 下 一 行 没有 被 使 


正确 的 


法 如 下 ， 每 次 使 


一 个 新 的 WebTarget 都 接收 WebTarget 的 方法 调 有 


， 原 来 的 WebTarget 实 例 并 没有 使 用 到 这 一 配置 。 见 关注 点 1。 


最 后 一 个 实例 作为 请 求 句柄 。 


WebTarget webTarget = client.target 
(BASE URI 

ya 

WebTarget pathTarget = webTarget .path 
("books" 

2 


WebTarget pathTarget2 = pathTarget .path 
("book" 

) ;i; 

WebTarget queryTarget = pathTarget2.queryParam 
("pookId", "1" 

Ys 


final Invocation.Builder invocationBuilder = 
queryTarget .request 
(MediaType.APPLICATION XML 


http://localhost:9527/client/books/book?bookId=1 


5.1.3 ”Invocation 接 口 


是 在 完成 资源 定位 配置 后 ， 向 REST 服 务 端 发 起 请 求 的 接 


Invocation 接 口 


口 。 请 求 包括 同步 和 异步 两 种 方式 ， 


nvocation 接 口内 部 的 Builder 接 


定义 ，Builder 接 


继承 了 同步 接 


Synclnvoker 中 定义 了 标准 的 HTTP 请 求 方法 。Jersey 对 JAX-RS 2.0 的 Invocation 接 


Invocation.Builder 接 口 


的 实现 类 是 org.glassfish.jer: 


实例 分 别 执行 了 GET 请 求 和 POST 请 求 来 提交 查询 和 创建 。 默 认 情况 下 ，HTTP 方 法 调 有 


sey.client.Jerseylnvocation。 


Synclnvoker。 


的 返回 


类 型 是 Response 类 型 ， 同 时 也 支持 泛 型 类 型 的 返回 值 。 


final Invocation.Builder invocationBuilder = 
queryTarget .request (MediaType .APPLICATION XML); 
final Book book = invocationBuilder.get (Book.class); 


Invocation.Builder invocationBuilder = target () .path (AtupApi .USER PATH) .request (); 


Response response = invocationBuilder.post (userEntity); 


5.2 ”资源 释放 


作为 REST 框 架 ，JAX-RS 2.0 不 希望 


等 资源 管理 细节 。 也 许 开发 者 的 编码 没有 使 


Response 的 readEntity()， 而 是 直接 返 


回 


发 者 编码 实现 对 客户 端 实例 的 资源 管理 ，Response 实 例 的 readEntity() 在 返 


泛 型 类 型 的 对 象 ， 然 而 其 底 


可 响应 实体 的 同时 ， 即 完成 了 对 客户 端 资源 的 释放 。 因 此 ， 开 发 者 无 须 担心 连接 、 释 放 
慨 还 是 使 用 了 这 个 方法 。 我 们 可 以 从 图 5-1 所 示 的 调用 栈 示意 图 中 一 探究 竟 。 


ES Debug > 蜗 Servers 
中 Thread iman pended 
三 InboundMessageContext$EntityContent.close[boolean) line: 153 
三 InboundMessageContext$EntityContent.close() line: 145 
三 QicentResponsec{InboundMessageContext).recedEntity(Class<T>, Type, Annotetion[], ProperticsDelegat 
三 QicentRespon .recedEntity(ClassxT», ProperticsDelegate) line:; 785 


三 InboundJaxrsResponse.rcadEntty(Cless<T>] line: 96 

三 Jerseylnvocation.transleta(CllentResponse, RequestScope, Class<T>) line: 761 
三 Jerseyinvocation.access$500(JerseyInvocation, ClientResponse, RequesiScope, Class) line: 90 
三 Jerseyfnvocation$2.call0 line: 671 

三 Errors.process(Callable<T>, boclean] line: 315 

三 Errors.process(Producer<T>, boclean] lina: 297 

三 Errors.process(Producer<T>) line: 228 

三 RequestScope.runinSscopelProducer<T>) line: 422 

三 Jerseyinvocation invoke(Class<T>) line: 667 

三 Jerseyinvocation$Builder,.method(String, Class <T>) line: 396 

三 Jerseyinvocation$Builder,get(Class <T>) line: 296 


三 DefaultCientJaxrs2Client).test0 line: 40 


三 TestDefaultClient,.testTalk0 line: 10 


t 志 EntityinputStream.class 总 > 


QOverri de 
public void cloce() throws ProcessineExcepticn { 
try { 
input. close() 
] cateh (TOFxception ex) { 
threw new ProcessingExcepti on [Locali zaticrMessagee. NESSAGE CONTENT JIFIT STREAN CLOSE FAIIED(), ex). 
】 finmally [ 


closed = true: 


1 

public class Jexrs2Client { 

publiec void test0O { 

final WabTarget webTarget = clicnt. target (JexrsaClient BASE UAT). 
final WoebTorget PathJarget = woebTlergat. path( "books”).; 
final Woblarget pathJsarget2 = pathlargot. path(“book” ). 
final WebTarget qusrylereet = pathlarget2. query7arsmi bookld”, “1°).; 
Jaxrs2Client. LOGGER debue (queryTsreet. getVri'!)). 
final Invocatior Bailder inwocaticnBuil der = querylereet. requect (Medialype. APPLICATION INL). 


roadhnt 11] cloce tha 


Jaxrr cICliont. LOCCER debug (book) 


图 5-1 REST 请 求 连接 资源 释放 


如 图 5-1 所 示 ， 测 试 代码 使 用 Invocation.Builder 接 口 实例 执行 GET 请 求 ， 根 据 Debug 栈 信息 ， 可 以 发 现 readEntity() 方 法 的 身影 ， 对 应 显示 line 为 96 的 一 行 。 再 往 下 的 栈 进入 了 输入 流 类 中 ， 对 应 显示 
line 为 155 的 一 行 。 在 该 类 的 close0 方 法 中 ， 可 以 看 到 最 终 关闭 了 流 对 象 ， 资 源 得 以 释放 。 


5.3 ”连接 器 


Connector 接 口 是 REST 客 户 端 底层 连接 器 接口 ，Jersey 为 Connector 接 口 提供 了 4 个 实现 ， 如 图 5-2 所 示 。 


< ApacheConnector (org.glassfish.jersey.apache.connector): 


TT TT TT TTT 


9 GrizzlyConnector (org.glassfish,jersey.grizzly.connector) 


其 中 : 


" HttpUdConnector 类 位 于 jersey-client 包 ， 是 REST 客 户 端 的 默认 连接 器 。 


" ApacheConnector 类 位 于 jersey-apache-connector 包 。 


"GrizzlyConnector 类 位 于 jersey-grizzly-connector 包 。 


ey.Client) 


hJersey,test,InmemoryJnternal) 


图 5-2 Connector 接 口 实现 类 


“ InMemoryConnector 类 位 于 jersey-test-framework-provider-inmemory， 不 是 一 种 真实 的 HTTP 连 接 器 ， 而 是 使 用 JVM 调 用 来 模拟 HTTP 请 求 访问 。 


接 下 来 ， 我 们 分 别 认 识 一 下 这 4 种 连接 器 。 


1. 默 认 连 接 器 


在 默认 情况 下 ，Jersey 对 JAX-RS 2.0 的 Connector 接 口 的 实现 类 是 org.glassfish.jersey.client.HttpUrlConnector。 如 果 开 发 者 不 显 式 地 配置 org.glassfish.jersey.client.ClientConfig， 那 么 在 Client 初 
始 化 时 会 默认 构造 一 个 HttpUrlConnector 类 的 实例 作为 连接 器 ， 源 代码 示例 如 下 。HttpUrlConnector 类 底层 的 连接 使 用 HttpPURLConnection 类 。 


if (state.getConnector () == null) { 
state.setConnector (new HttpUrlConnector ()); 
} 


2.Apache 连 接 器 


ApacheConnector 是 基于 Apache HTTP Client 的 连接 器 实现 ， 相 比 默 认 的 连接 器 功能 更 完整 、 强 大 。 在 Client 实 例 中 使 用 ApacheConnector 是 通过 配置 ClientConfig 的 connector 来 实现 的 ， 示 例 代 


码 如 下 。 


final ApacheConnector connector = new ApacheConnector 


(clientConfig 
二 
clientConfig.connector 

(connector 


client = ClientBuilder.newClient 
(clientConfig 


在 这 段 代 码 中 ，ClientConfig 实 例 在 Client 加 载 前 ， 完 成 了 对 connector 的 配置 ， 该 connector 是 一 个 ApacheConnector 实 例 。ClientConfig 实 例 还 可 以 配置 和 Apache 连 接 器 相关 的 属性 ， 示 例 代码 如 


// 

关注 点 1 

: 代理 服务 器 配置 

clientConfig.property 
(ApacheClientProperties.PROXY URI, "http://192.16 

clientConfig.property 
(ApacheClientProperties.PROXY USERNAME, "erichan" 

clientConfig.property 
(ApacheClientProperties.PROXY PASSWORD , "***" 


// 

关注 点 2; 

连接 超时 设置 

clientConfig.property 
(ClientProperties.CONNECT TIMEOUT, 1000 
); 
clientConfig.property 
(ClientProperties.READ TIMEOUT, 2000 


8.0.100" 


在 这 段 代码 中 ， 分 别 设置 了 代理 服务 器 和 超时 时 间 。 代 至 
时 设置 ， 见 关注 点 2。 详 情 随 后 讲述 。 


服务 器 的 设置 包括 代理 


服务 器 地 址 、 


户 名 和 密码 (代码 中 以 星 号 代替 ) ， 见 关注 点 1。 连 接 超时 设置 包括 物理 


连接 超时 时 间 设 置 和 读 取 数 据 超 


ApacheConnector 内 部 使 用 DefaultHttpClient 作 为 底层 的 连接 。DefaultHttpClient 内 部 定义 了 org.apache.http.conn.ClientConnectionManager 接 口 和 org.apache.http.params.HttpParams 接 


可 以 改变 客户 端 实例 加 载 的 策略 ， 以 提高 客户 端 连 接 处 理 的 性 能 ， 可 参考 本 节 “HTTP 连 接 池 ” 相 关内 容 。 


(1) 代理 服务 器 设置 


口 ， 分 别 通过 配置 属性 ApacheClientProperties.CONNECTION_MANAGER 和 ApacheClientProperties.HTTP_PARAM S 来 定义 ， 默 认 情况 下 都 是 null。 通 过 定义 ClientConnectionManager 接 口 的 实例 ， 


通过 jersey-apache-connector 包 提供 的 属性 值 ApacheClientProperties.PROXY_URI， 可 以 在 Client 实 例 中 使 用 HTTP 代 理 服务 器 ， 常 量 ApacheClientProperties.PROXY_URI 的 值 是 
jersey.config.apache.client.proxyUri， 用 于 配置 代理 服务 器 地 址 ， 常 量 ApacheClientProperties.PROXY_USERNAME 和 ApacheClientProperties.PROXY_PASSWORD 分 别 用 于 配置 代理 服务 器 的 用 户 名 


和 密码 。 


(2) 超时 设置 


默认 情况 下 ， 连 接 超 时 和 读 取 超时 是 不 设置 的 ， 就 是 说 客户 端 一 直 尝 试 连接 或 者 读 取 ， 直 到 | 成 功 或 被 服务 器 主动 断 开 为 止 。 


通过 设置 ClientProperties.CONNECT_TIMEOUT， 可 以 定义 客户 端 尝试 连接 的 最 长 时 间 ， 单 位 是 毫秒 (ms) ， 当 超出 这 个 时 间 后 ， 客 户 端 会 主动 放弃 连接 并 抛 出 超时 异常 


ConnectTimeoutException。 


读 取 超 时 是 指 连 接 和 资源 定位 成 功 后 ， 客 户 端 接收 服务 器 响应 消息 的 最 长 时 间 。 通 过 设置 ClientProperties.READ_TIMEOUT， 可 以 定义 客户 端 读 取 超 时 时 间 ， 单 位 是 毫秒 ， 当 超出 这 个 时 间 后 ， 客 户 端 


会 主动 关闭 连接 ， 并 抛 出 SocketTimeoutException 异 常 。 
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Grizzly 连 接 器 


GrizzlyConnector 是 Grizzly 提 供 的 连接 器 实现 ， 其 内 部 使 用 异步 处 理 客户 端 com.ning.http.client.AsyncHttpClient 类 作为 底层 的 连接 ， 该 类 来 自 于 AsyncHttpClient 项 目 (地 址 是 


https://github.com/AsyncHttpClient) 。 该 项 目的 2.0 版 本 将 Maven 的 坐标 信息 进行 了 更 改 : groupld 从 com.ning.http.client 改 为 org.asynchttpclient，com.ning.http.client 包 名 改 为 
org.asynchttpclient。 读 者 在 引用 Grizzly 连 接 器 时 应 当 注 意 所 用 版 本 的 Maven 坐 标 是 否 符合 上 述 定义 。 


AsyncHttpClient 使 用 GrizzlyAsyncHttpProvider 处 理 HTTP 请 求 异步 事件 ，GrizzlyAsync HttpProvider 是 AsyncHandler 接 口 的 实现 类 。 


在 Client 实 例 中 使 用 GrizzlyConnector 是 通过 配置 ClientConfig 的 connector 来 实现 的 ， 示 例 代 码 如 下 。 


final GrizzlyConnector connector = new GrizzlyConnector (clientConfig) 7 
clientConfig.connector (Connector) 7 
client = ClientBuilder.newClient (clientConfig); 


在 这 段 代 码 中 ，ClientConfig 在 Client 加 载 前 ， 配 置 connector 为 GrizzlyConnector 实 例 。 


4.HTTP 连 接 池 


在 讲述 完 连 接 器 后 ， 我 们 回 到 Client 是 重型 组 件 这 个 问题 。Client 的 内 部 不 只 是 简单 地 包含 一 个 HTTP 连 接 器 的 设计 ， 而 是 携带 了 诸如 资源 状态 等 信息 ， 因 此 在 系统 中 频繁 地 创建 Client 实 例会 影响 总 体 


的 性 能 。 一 种 常见 的 解决 方案 是 使 用 HTTP 连 接 池 来 管理 连接 ， 而 不 是 每 次 请 求 都 创建 一 个 Client 实 例 。 


这 里 使 用 ApacheConnector 来 实现 HTTP 连 接 池 ， 示 例 代码 如 下 。 


final ClientConfig clientConfig = new ClientConfig(); 

final SchemeRegistry registry = new SchemeRegistry(); 

registry.register (new Scheme ("http", 8080, PlainSocketFactory.getSocketFactory())); 
a PoolingClientConnectionManager cm = new PoolingClientConnectionManager (registry); 


My 点 1 

: 配置 连接 池 管 理 实例 
cm.setMaxTotal (20000); 
cm.setDefaultMaxPerRoute (10000); 
Sy 


i 

: 将 连接 池 管 理 实例 配置 为 ClientConfig 

的 属性 值 

clientConfig.property (ApacheClientProperties .CONNECTION MANAGER, cm); 
a 


关注 点 3 

: 传递 客户 端 配置 实例 给 连接 器 

final ApacheConnector connector = new ApacheConnector (clientConfig); 
clientConfig.connector (connector); 

Pe 


关注 点 4 

客 端 醒 置 实例 携带 了 Apache 
连接 器 信息 
Client = ClientBuilder.newClient (clientConfig); 


在 这 段 代 码 中 ， 首 先 定义 了 连接 池 管理 实例 ， 该 实例 通过 setMaxTotal0 方 法 设置 了 最 大 连接 数 ， 通 过 setDefaultMaxPerRoute() 方 法 设置 了 每 条 路 由 的 默认 最 大 连接 数 ， 见 关注 点 1。ClientConfig 的 


属性 ApacheClientProperties.CONNECTION_MANAGER 用 于 定义 连接 池 管理 实例 ， 其 属性 值 为 ClientConnectionManager 接 tein 该 类 是 线程 安全 
的 ， 


支持 多 线程 并 发 操作 ， 见 关注 点 2。ApacheConnector 的 初始 化 需要 设置 ClientConfig 实 例 ， 该 实例 在 加 载 到 连接 器 之 前 可 以 将 REST 客 户 端 参数 配置 好 ， 在 连接 器 初始 化 后 将 其 配置 到 自身 的 


connector 属 性 中 ， 见 关注 点 3。 最 后 ，ClientBuilder 使 用 携带 了 连接 器 信息 的 ClientConfig 实 例 创建 的 REST 客 户 端 实例 ， 即 可 实现 对 ApacheConnector 连 接 器 的 使 用 ， 见 关注 点 4。 
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Ek 


.4 封装 Client 


通常 ，REST 式 的 Web 服 务 会 按 模块 分 别提 供 独 立 的 Web 服 务 ， 而 模块 之 间 的 调用 通过 Web 服 务 的 REST APl 来 实现 。 因 此 ， 每 个 模块 对 其 他 模块 的 调用 即 是 客户 端 请 求 ， 不 必 在 每 次 请 求 时 重复 编写 构 


客户 端 实例 的 代码 。 为 此 ， 抽 象 出 Client 到 公共 模块 是 非常 有 必要 的 。 封 装 Client 可 以 减少 代码 匈 余 ， 也 为 统一 Client 构 建筑 略 (避免 配置 不 统一 带 来 的 混乱 ) 提供 了 可 能 。 


如 下 代码 片段 来 自 第 11 章 综合 实例 的 atup-core 模 块 。rest0 方 法 封装 了 HTTP 请 求 ， 参 数 依次 是 HTTP 请 求 方法 名 、 请 求 资源 地 址 、 请 求 头 参数 、 请 求 查询 参数 、 请 求 媒体 类 型 、 返 回 值 类 型 、 请 求实 体 


息 


E\o 


public T rest (String method, String requestUrl, Set<AtupRequestParam>headParams, 
Set<AtupRequestParam>queryParams, MediaTyperequestDataType, 
Class<T>returnType, T requestData) { 

要 


关注 点 1 
: 构造 Client 
if (clientConfig =—= null) { 
clientConfig = new ClientConfig(); 
} 
Client client = ClientBuilder.newClient (clientConfig); 
if (!CollectionUtils.isEmpty(clientRegisters)) { 
for (Class<?>clazz : clientRegisters) { 
client.register (clazz); 
} 
} 
// 
关注 点 2 
: 构造 WebTarget 
WebTarget webTarget = client.target (requestUr1) 7 
if (!CollectionUtils.isEmpty (queryParams)) { 
for (AtupRequestParam atupRequestParam : queryParams) { 
webTarget = webTarget .queryParam (atupRedquestParam.getKey (), 
atupRequestParam.getValue () ) 


关注 点 3 


: 构造 Invocation.Builder 


Invocation.Builder invocationBuilder = webTarget .request (requestDataType); 


if (!CollectionUtils.isEmpty (headParams)) { 
for (AtupRequestParam atupRequestParam : headParams) { 
invocationBuilder.header (atupRequestParam.getKey (), 
atupRequestParam.getValue () ) 7 
} 
} 
// 
关注 点 4 
: 发 起 请 求 和 结果 处 理 
javax.ws.rs.core.Response response; 
Entity<T> entity; 
switch (method) { 
case GET: 
response = invocationBuilder.get (); 
return response.readEntity (returnType); 
Case DELETE: 
response = invocationBuilder.delete(); 
return response.readEntity (returnType); 
case PUT: 
entity = Entity.entity (requestData, requestDataType); 
response = invocationBuilder.put (entity); 
return response.readEntity (returnType); 
case POST: 
entity = Entity.entity (requestData, requestDataType); 
response = invocationBuilder.post (entity); 
return response.readEntity (returnType); 
default: 
return null; 


在 这 段 代 码 中 ，rest() 方 法 可 以 分 为 4 个 部 分 ， 第 一 部 分 是 构造 Client， 见 关注 点 1; 第 二 部 分 是 构造 WebTarget， 见 关注 点 2; 第 三 部 分 是 构造 Invocation.Builder， 见 关注 点 3; 最 后 一 部 分 是 发 起 请 求 


和 结果 处 理 ， 见 关注 点 4。 


5.5 ”本 章 小 结 


本 章 讲述 了 JAX-RS 2.0 定 义 的 REST 客 户 端 及 其 初始 化 ， 主 要 的 接口 包括 Client、WebTarget 和 Invocation。 客 户 端 的 实现 需要 注意 的 是 客户 端的 实例 数量 不 宜 过 多 ， 可 以 根据 情况 使 用 5.3 节 讲述 的 连 
接 器 来 避免 每 次 请 求实 例 化 一 个 客户 端的 情况 。 最 后 ，5.4 节 演示 了 REST 客 户 端的 初始 化 代码 块 的 封装 和 复 用 。 下 一 章 ， 我 们 开始 讲述 REsT 的 安全 内 容 。 


第 二 篇 


m 第 6 章 REST 安 全 

@ 第 7 章 JREST 测 试 

和 第 8 章 ” REST 推送 与 异步 通信 
和 第 9 章 Jersey1.x 迁 移 


m 第 10 章 JAX-RS 调 优 


第 6 章 ” REST 安全 


全 面 掌握 一 一 JAX-RS 2.0 进 阶 


REST 式 的 Web 服 务 提供 了 统一 接口 和 资源 定位 ， 简 化 了 Web 服 务 接口 的 设计 和 实现 ， 降 低 了 Web 服 务 的 复杂 度 。 但 是 ,与 此 同时 ， 易 于 识别 和 理解 的 REST 接 口 也 存在 着 易于 破解 的 危险 。 如 果 破 坏 者 


通过 对 Web 服 务 资源 地 址 的 猜 解 ， 获 取 了 删除 某 一 资源 的 接口 并 对 该 Web 服 务 进行 攻击 ， 那 么 很 容易 造成 系统 数据 的 破坏 。 因 


的 阐述 。 


此 ，REST 式 的 Web 服 务 的 安全 性 至 关 重要 。 本 章 将 对 REST 的 安全 性 进行 全 面 


简 而 言 之 ， 实 现 安全 的 过 程 就 是 系统 实现 AAA 的 过 程 。AAA 是 指认 证 (Authentication) 、 授 权 (Authorization) 和 账户 (Accounting) 。 


什么 是 认证 呢 ? 认证 就 是 系统 识别 访问 者 身份 的 过 程 。 举 个 例子 ， 比 如 交警 对 司机 进行 交通 检查 ， 


“认证 ”就 是 交警 确认 驾驶 者 是 该 车 的 准 驾 司机 的 过 程 。 如 果 是 双向 认证 ， 还 包括 驾驶 者 对 交警 身份 
确认 的 过 程 。 什 么 是 授权 呢 ? 还 用 这 个 小 例子 ， 授 权 就 是 当 交 警 确认 并 记 住 (系统 是 通过 Cookie、 加 密 的 URI 或 者 Session) 驾驶 者 的 司机 身份 后 ， 对 该 准 各 类 型 的 司机 授予 的 权限 进行 监控 的 过 程 。 比 如 小 
型 客车 的 司机 在 驾驶 一 辆 大 型 货车 ， 那 么 该 驾驶 者 没有 权限 这 样 做 ， 交 警 将 对 其 依法 处 置 (系统 拒绝 访问 者 访问 ， 返 回 HTTP 状 态 码 403) 。 


那么 ， 认 证 是 如 何 实现 的 呢 ? 简单 的 认证 方式 是 通过 用 户 名 一 密码 (也 称 口令 ) 进行 验证 。 访 问 者 在 服务 器 提出 身份 质询 后 做 出 反馈 ， 即 (加密 ) 提交 用 户 名 和 密码 ， 服 务 器 端 接收 该 信息 并 对 其 进行 


验证 。 用 户 名 一 密码 验证 方式 的 实现 比较 简单 、 易 行 ， 但 很 容易 被 盗 取 和 破解 即使 经 过 加 密 处 理 ) 。 


除了 用 户 名 一 密码 验证 方式 ， 还 可 以 通过 数字 证 书 进 行 验证 ， 但 验证 过 程 相 对 复杂 。 还 以 交通 检查 为 例 ， 过 程 如 下 。 


首先 ， 驾 驶 者 出 示 驾 照 (数字 证 书 ， 访 问 者 身份 的 凭据 ) 。 交 警 拿 到 驾照 后 ， 首 先 核实 驾照 的 真 伪 (数字 证 书 是 否 是 伪造 的 ) ， 判 断 的 依据 是 核对 驾照 上 是 否 有 交警 支队 的 印章 [CA (Certificate 
Authority， 权 威 的 数字 证 书 认 证 机 构 ) 签发 的 数字 证 书 ]， 还 要 判断 这 个 印章 的 真 伪 (CA 是 否 在 对 方 的 信任 证 书 列表 中 。 这 个 验证 过 程 可 能 包括 对 CA 身份 的 验证 ， 比 如 交警 支队 的 身份 由 交通 部 门 的 印章 来 
确认 ， 直 至 追溯 到 双方 都 确信 的 CA 出 示 的 根 证 书 。 本 例 中 ， 交 警 信任 交警 支 了 从， 所 以 交警 支队 的 印章 可 以 看 做 双方 都 信任 的 根 证 书 ) 。 接 着 ， 交 警 要 查看 证 书 的 有 效 期 等 信息 ， 保 证 证 书 合法 、 有 效 。 到 


此 ， 交 警 确认 了 和 驾照 的 合法 性 (服务 器 对 客户 端的 数字 证 书本 身 的 校 验 完毕 ) 。 


最 后 ， 交 和 警 会 查看 驾照 上 对 轰 驶 者 身份 等 信息 的 描述 ， 来 确认 其 身份 和 准 驾车 类 型 (这 个 步骤 相当 于 服务 器 从 证 书 中 获取 访问 者 的 身份 信息 ) 。 认 证 过 程 中 ， 使 用 了 诸多 安全 技术 ， 比 如 加 密 算法 、 摘 
要 算法 、 公 钥 / 私 钥 对 、 证 书生 成 一 导入 一 导出 一 吊销 等 。 授 权 的 实现 可 以 由 容器 级 别 的 配置 完成 ， 或 者 通过 程序 级 别 的 注解 和 编码 完成 。 


在 了 解 了 认证 和 授权 的 过 程 后 ， 我 们 从 简 述 理论 到 实践 ， 逐 一 讲述 REST 中 可 以 采用 的 认证 和 授权 办 法 。 


图 闲 读 指南 本 章 示例 所 在 目录 是 jax-rs2-guide\sample\6\security-rest。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/6/security-rest。 


6.1 身份 认证 


HTTP 认 证 规范 (RFC 2617) 定义 了 两 种 HTTP 身 份 认证 方式 : HTTP Basic (基本 认证 ) 和 HTTP Digest (摘要 认证 ) 。HTTP 认 证 是 一 种 无 状态 的 认证 方式 ， 服 务 器 容器 不 会 为 这 样 的 登录 匹配 
Session， 身 份 信息 随 浏览 器 关闭 而 消失 。Java 平 台 包含 了 HTTP 的 两 种 身份 认证 ， 此 外 还 定义 了 HTTP+HTML form-based authentication (表单 认证 ) 和 证 书 认证 。 


基本 认证 、 摘 要 认证 和 表单 认证 都 是 基于 “用 户 名 一 密码 ”的 认证 机 制 ， 而 证 书 认证 是 基于 证 书 的 认证 机 制 。 基 本 认证 和 表单 认证 的 请 求 过 程 需要 提交 用 户 的 密码 信息 ， 而 且 对 服务 器 的 合法 性 缺乏 判 
断 依据 ， 摘 要 认证 和 证 书 认证 的 请 求 过 程 将 对 服务 器 的 合法 性 进行 验证 而 且 不 直接 提交 用 户 的 密码 。 


下 面 将 对 这 4 种 认证 方式 逐一 讲述 。 


6.1.1 基本 认证 


HTTP 的 基本 认证 最 初 定义 在 HTTP 1.0 规 范 (RFC 1945) 中 ， 后 续 最 新 的 定义 包含 于 HTTP 1.1 规 范 (RFC 2616) 和 HTTP 认 证 规范 (RFC 2617) 。HTTP 基 本 认证 是 指 通过 Web 浏 览 器 或 其 他 客户 端 在 
发 送 请 求 时 ， 提 供用 户 名 和 密码 作为 身份 凭证 的 一 种 登录 验证 方式 。 在 请 求 发 送 之 前 ， 用 户 名 和 密码 字符 串通 过 一 个 冒号 合并 ， 形 如 : Username:Password， 合 并 后 的 字符 串 经 过 Base64 算 法 进行 编码 。 


例如 ， 提 供 的 用 户 名 是 eric、 密 码 是 han， 合 并 后 为 erichan， 经 过 Base64 算 法 进行 编码 后 


符 串 为 ZXJpYzpoYW4=。 


寺 


浏览 器 或 客户 端 最 终 将 经 过 Base64 编 码 的 字符 串 提交 给 服务 器 。Base64 编 码 的 目的 并 不 是 实现 安全 与 隐私 ， 而 是 为 了 将 用 户 名 和 密码 中 的 与 HTTP 不 兼容 的 字符 转换 为 兼容 的 字符 集 。 


HTTP 基 本 认证 的 请 求 过 程 是 一 个 质询 /回应 (challenge/response) 的 对 话 流程 ， 即 客户 端 请 求 一 个 需要 身份 认证 的 资源 路 径 ， 但 是 没有 提供 用 户 名 和 密码 。 服 务 器 端 响应 HTTP 状 态 码 
401 (Unauthorized) 的 应 答 ， 并 提供 一 个 认证 域 (Basic realm) 。 客 户 端 增加 认证 消息 头 ， 内 容 为 前 述 的 Base64 加 密 字符 串 ， 形 式 为 Authorization:Basic base64encode (Username:Password) ， 
并 再 次 发 起 请 求 。 服 务 器 端 接收 请 求 并 处 理 ， 如 果 用 户 凭 据 非法 或 无 效 ， 服 务 器 可 能 再 次 返回 HTTP 状 态 码 401， 客 户 端 可 以 再 次 提示 用 户 输入 密码 。 质 询 /回应 会 话 流程 是 可 以 省 略 的 ， 即 在 客户 端 第 一 次 请 
求 中 就 发 送 认 证 消息 头 。 


6.1.2 ”摘要 认证 


摘要 认证 最 初 定义 在 RFC 2069 (HTTP 的 一 个 扩展 : 摘要 访问 认证 ) 中 ， 以 服务 器 生成 的 随机 数 来 维护 安全 性 。RFC 2069 中 定义 的 认证 响应 由 HA1、HA2、A1 及 A2 组 成 。 其 中 ，nonce 是 服务 器 端 随 
机 数 。 后 续 最 新 的 定义 包含 于 HTTP 认 证 规范 (RFC 2617， 是 RFC 2069 的 替代 方案 ) 。RFC 2617 引 入 了 一 系列 安全 增强 的 选项 ， 包 括 QoP (Quality of Protection， 保 护 质量 ) 、 请 求 计数 器 
nc (nonceCount) 和 cnonce (clientNonce， 客 户 端 随机 数 ) 。 这 些 增强 项 有 效 地 防止 了 通信 过 程 中 的 明文 攻击 。RFC 2617 中 对 A2、HA2 和 response 做 了 如 下 增强 定义 ， 见 表 6-1。 


表 6-1 RFC 2069 和 RFC 2617 摘 要 认证 参数 列表 


参数 组 合 
Al=Username:Realm:Password 
A2=method:digestURI 
HAl1=MD5S (A1) 

HA2=MD5 (A2) 
Tesponse=MD5 (HAl:nonce:HA2) 


说 明 
qop=auth/NONE 时 ，A2=method:digestURI 
qop=auth-int 时 ，A2=method:digestURIMD5 (entityBody) 
qop=NONE 时 ，response=MD5S (HAl:nonce:HA2) 
qop=auth/auth-int 时 ，response=MD5 (HA1:nonce:nonceCount:clie 
ntNonce:qop:HA2) 


HTTP 摘 要 认证 同样 遵循 请 求 过程 的 质询 /回应 对 话 流程 。 具 体 描述 参考 上 文中 的 基本 认证 。 


6.1.3 ”表单 认证 


表单 认证 是 基于 HTTP， 使 用 HTML 的 Form 标 签 提交 表单 的 认证 形式 。 用 户 登录 页 面 定 义 在 web.xml 文 件 的 form-login-page 字 段 中 ， 在 没有 被 认证 前 ,访问 者 对 资源 地 址 的 访问 会 被 引导 到 该 页 面 。 
访问 者 提交 身份 信息 后 ， 服 务 器 接收 并 处 理 请 求 ， 如 果 认证 通过 ， 将 重 定向 到 welcome-file 字 段 定义 的 页 面 ， 如 果 失 败 ， 将 重 定向 到 form-error-page 字 段 定义 的 页 面 。 相 对 于 HTTP 认 证 ， 表 单 认证 允许 开 
发 者 指定 并 设计 具有 良好 用 户 体验 的 登录 页 面 、 登 录 成 功 页 面 和 登录 失败 页 面 。 


Java 平 台 处 理 表单 认证 的 实现 是 在 客户 端 页 面 (比如 HTML+AJAX、JSP、JSF 等 ) 中 ， 定 义 一 个 名 称 指定 为 _security_check 的 请 求 方法 ， 该 方法 传递 两 个 名 称 固定 的 字段 。 用 户 名 字段 为 
j_username， 密 码 字段 加 _password。 服 务 器 端 会 根据 上 述 固 定名 称 对 提交 的 表单 进行 解析 和 验证 ， 示 例 代码 如 下 。 


<form method="POST" action="j security check"> 
<input type="text" name="j username"> 
<input type="password" name="j password"> 
</form> 


6.1.4 证 书 认证 


证 书 认 证 是 通过 数字 证 书 认 证 身份 的 方式 。 这 一 方式 从 技术 角度 可 以 拆 分 为 证 书 管理 和 通信 协议 两 个 环节 。 证 书 是 静态 的 文件 ， 为 基于 SSL/TLS 协 议 的 通信 过 程 所 用 。 


1. 证 书 


证 书 是 包含 公 铜 和 密 钥 属 主 信息 的 文件 。 加 密 是 为 了 将 信息 保密 且 完 整地 传递 出 去 ， 加 密 算 法 是 实现 这 一 过 程 的 手段 。 持 有 加 密 算法 的 文件 即 为 密 铀 ， 密 钥 分 为 公 铜 和 私 铀 ， 在 加 密 、 解 密 环 节 ， 公 和 钥 
于 加 密 ， 私 钥 用 于 解密 。 


当 甲 持 有 乙 的 证 书后 ， 甲 就 可 以 从 该 证 书 中 获取 乙 的 公 钥 。 使 用 该 公 钥 对 数据 进行 加 密 ， 然 后 发 送 给 乙 ， 乙 使 用 私有 的 私 钥 将 数据 解密 。 在 这 一 过 程 中 ,信息 的 保密 性 和 完整 性 得 到 了 保障 ， 但 安全 性 
中 的 端点 认证 无 法 通过 加 密 /解密 解决 。 也 就 是 说 ， 甲 无 法 确认 接收 者 就 是 乙 。 


证 书 认 证 解决 了 端点 认证 的 两 个 问题 。 


第 一 个 问题 是 验证 接收 者 是 乙 。 在 签名 环节 ， 私 钥 用 于 签名 ， 公 钥 用 于 校 验 。 乙 的 公 钥 就 像 乙 手写 签名 的 快照 一 样 ， 只 有 乙 本 人 的 签名 ( 乙 的 私 钥 ) 才 与 之 能 匹配 。 


第 二 个 问题 是 验证 证 书 的 合法 性 。 通 信 过 程 中 ， 对 方 提交 的 证 书 说 他 是 乙 ， 那 么 甲 如 何 相信 证 书 及 其 所 言 呢 ? 这 需要 使 用 或 间接 使 用 另 一 个 权威 证 书 来 鉴定 该 证 书 的 合法 性 ， 读 者 可 以 回忆 一 下 前 面 说 
过 的 交警 支队 需要 交通 部 门 来 证 明 其 真 伪 的 例子 ， 这 就 是 证 书 链 模型 。 该 模型 最 简 版 本 为 甲乙 互相 信任 ， 这 种 情况 下 无 须 CA 证 书 参与 进来 。 最 复杂 的 版 本 就 是 甲乙 只 相信 最 权威 的 CA 认证 机 构 ， 而 他 们 持 
有 的 认证 证 书 却 都 不 是 直接 来 自 那个 机 构 签发 的 。 通 过 证 书 链 逐 级 上 溯 ， 最 终 ， 甲 通过 信任 CA 来 认可 当前 证 书 是 为 乙 颁发 的 ， 这 样 一 来 ， 只 要 乙 的 私 钥 签名 在 经 过 证 书 公 钥 校 验 后 结果 一 致 ， 甲 就 可 以 相信 
接收 者 就 是 乙 。 


证 书 的 签发 格式 遵循 X.509 标 准 。X.509 是 由 国际 电信 联盟 〈ITU-T) 制定 的 数字 证 书 标准 。 证 书 的 管理 可 以 通过 OpenSSL (http//www.opensslorg) 和 Java 平 台 的 keytool 工 具 来 实现 ， 本 章 实例 部 
分 将 使 用 keytool 来 实现 证 书 的 管理 。 


2.SSL/TLS 


SSL (Secure Socket Layer， 安 全 套 接 层 协议 ) 是 在 传输 通信 协议 (TCP/IP) 上 实现 的 一 种 安全 协议 ， 采 用 公 钥 技术 保证 数据 的 保密 性 和 完整 性 。HTTPS 是 运行 在 SSL 协 议 之 上 的 HTTP， 其 本 质 还 是 
SSL 通 信 。1ETF 组 织 将 SSL 标 准 化 后 成 为 TLS (Transport Layer Security， 传 输 层 安全 协议 ) (RFC 2246) 。SSLv2 已 经 过 时 ，TLS 1.0 非 常 近似 SSLv3， 本 书 余 文 使 用 TLS 代 蔡 SSL/TLS 的 书写 方式 。 


TLS 包 含 三 个 基本 阶段 : @ 对 等 协商 密 钥 算法 ;@ 传 输 基 于 非 对 称 密 铀 加 密 的 数据 和 基于 PKI (Public Key Infrastructure， 公 钥 基 础 设施 ) 证 书 的 身份 认证 ; @@ 传 输 基于 对 称 密 钥 加 密 的 数据 。 


3JSR219 


在 Java 领 域 ， 证 书 管理 、 对 TLS 的 支持 定义 在 JSR 219 中 。JSR 219 规 范 (Foundation Profile 1.1Java 平 台 对 安全 领略 支持 的 规范 ) 包括 3 个 标准 : JCE (Java Cryptography Extension) 、JSSE (Java 


Secure Sockets Extension) 、JAAS (Java Authentication and Authorization Service) 。 
“JCE 定 义 了 Java 对 加 密 / 解 密 、 密 钥 生 成 和 协商 ， 以 及 MAC (Message Authentication Code， 消 息 认证 码 ) 算法 的 实现 规范 。 
“JSSE 定 义 了 Java 对 安全 传输 和 握手 机 制 的 实现 规范 ， 包 含 了 对 SSL/TLS 的 支持 。 


"JAAS 是 Java 平 台 认 证 和 授权 的 标准 。JAAS 建 立 在 PAM (Pluggable Authentication Module， 可 插入 的 认证 模块 ) 安全 体系 结构 之 上 ， 一 方面 ， 使 业务 逻辑 和 安全 校 验 解 耦 ; 另 一 方面 ， 提 供 了 23 种 设计 模 
式 中 责任 链 模式 的 校 验 过程 ， 使 模块 化 的 校 验 机 制 可 插 拔 地 无 颖 集成 于 业务 平台 中 。 


6.2 ”资源 授权 


通过 上 文 的 讲述 ， 我 们 对 REST 应 用 中 可 以 采用 的 4 种 身份 认证 方式 有 了 初步 了 解 。 在 有 了 用 户 的 身份 信息 后 ， 服 务 器 要 做 的 事情 就 是 识别 该 用 户 对 REST 应 用 中 资源 的 访问 权限 。 授 权 管理 包括 容器 管理 
和 应 用 管理 。 


容器 管理 权限 提供 无 编码 的 、 可 配置 的 全 局 的 管理 方式 ， 零 编码 、 方 便 统 一 管理 。 应 用 管理 权限 提供 细 粒 度 的 权限 管理 ， 通 过 编码 使 具体 业务 的 权限 分 配 更 灵活 。 接 下 来 我 们 分 别 讲 述 两 种 授权 管理 的 
实现 。 


6.2.1 ”容器 管理 权限 


容器 管理 权限 是 指 容器 通过 启动 时 从 其 配置 文件 中 加 载 角色 一 权限 信息 ， 在 运行 时 对 用 户 身 份 进行 认证 ， 并 对 其 角色 的 资源 访问 权限 进行 管控 的 方式 。 


1. 基 于 Realm 的 身份 认证 


Java 平 台 的 servlet 容器 和 Java EE 容器 根据 规范 各 自 都 提供 了 认证 和 授权 的 实现 。 本 书 以 Tomcat 为 例 展示 容器 管理 权限 功能 。 


在 Tomcat 中 ， 使 用 Realm 作 为 用 户 身份 识别 的 基本 单位 ，Realm 这 个 概念 类 似 UNIX 下 的 groups，Tomcat 在 运行 期 根据 其 中 定义 的 role 与 访问 资源 的 匹配 ， 控 制 当前 用 户 的 访问 权限 。Realm 的 配置 通 
常 在 服务 器 配置 文件 conf/serverxml 中 定义 格式 。 在 Tomcat 配 置 文件 中 对 Realm 的 定义 示例 如 下 。 


<Realm className=" 

实现 org .apache.catalina.Realm 

接口 的 类 全 名 " http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 

该 实现 的 其 他 属性 http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/.../> 


Realm 项 可 以 内 置 于 任何 一 个 容器 项 中 ， 这 将 影响 该 realm 的 作用 域 (scope) 。 


' 内 置 于 Engine 项 : 该 Realm 将 作用 于 所 有 hosts 中 的 Web 应 用 ， 除 非 在 Host 项 或 者 Context 项 中 被 覆盖 。 
. 内 置 于 Host 项 : 该 Realm 将 作用 于 所 有 virtual host 中 的 Web 应 用 ， 除 非 在 Context 项 中 被 覆盖 。 
' 内 置 于 Context 项 : 该 Realm 将 只 作用 于 该 Web 应 用 。 


Tomcat 提 供 了 6 个 标准 的 Realm 认 证 插件 : JDBCRealm、DataSourceRealm、UserDatabaseRealm、JAASRealm、MemoryRealm (通过 读 取 XML 格 式 内 存 集合 对 象 ， 获 取 认 证 信息 。 这 是 一 个 过 
时 的 Realm， 目 前 被 UserDatabaseRealm 取 代 ) 和 JNDIRealm (通过 JNDI 访 问 LDAP 服 务 器 ， 获 取 认证 信息 ) 。 本 章 6.3 节 将 通过 5 个 示例 来 展示 如 何 结合 各 种 身份 认证 和 Tomcat 提 供 的 Realm 实 现 REST 应 
中 的 认证 和 授权 。 


2. 角 色 一 权限 配置 


配置 文件 中 定义 的 角色 一 权限 信息 是 使 用 XML 完 成 的 。 虽 然 在 很 多 架构 或 者 工具 的 发 展 过 程 中 ， 已 经 将 其 XML 格 式 的 配置 文件 转 为 注解 方式 ， 但 是 权限 配置 使 用 XML 定 义 的 方式 ， 层 次 更 清晰 。 容 器 管 
理 权限 的 配置 讲述 如 下 。 


(1) 配置 security-constraint 元 素 


security-constraint 元 素 用 来 定义 安全 约束 ， 包 括 可 访问 的 资源 、 访 问 者 身份 和 数据 传输 类 型 的 约束 。 


1) web-resource-collection: web-resource-collection 元 素 用 来 标识 需要 限制 访问 的 资源 子 集 。 在 web-resource-collection 元 素 中 ， 可 以 定义 url-pattern (使 用 资源 路 径 通配符 定义 的 资源 集合 ) 


和 http-method (HTTP 方 法 ) 。 如 果 不 存在 HTTP 方 法 ， 就 将 安全 约束 应 用 于 所 有 的 方法 。 
2) auth-constraint: auth-constraint 元 素 用 于 指定 可 以 访问 该 资源 集合 的 用 户 角色 。 如 果 没 有 指定 auth-constraint 元 素 ， 就 将 安全 约束 应 用 于 所 有 角色 。role-name 元 素 包含 安全 角色 的 名 称 。 


举例 说 明 ， 在 如 下 定义 中 ，user 角 色 可 以 访问 /webapi/* 资 源 集合 中 所 有 的 GET 方 法 。 


<security-constraint> 
<web-resource-collection> 
<web-resource-name>restful resources</web-resource-name> 
<url-pattern>/webapi/*</url-pattern> 
<http-method>GET</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>user</role-name> 
</auth-constraint> 
<user-data-constraint> 
<transport-guarantee>NONE</transport-guarantee> 
</user-data-constraint> 
</security-constraint> 


3) user-data-constraint: user-data-constraint 元 素 上 


INTEGRAL， 意 味 着 服务 器 和 客户 端 之 间 的 数据 必须 以 某 种 方式 发 送 ， 而 


(2) 配置 login-config 元 素 


来 指定 所 使 


login-config 元 素 的 验证 方法 、 领 域名 和 表单 验证 机 制 所 需 的 特性 。 


1) auth-method: auth-method 指 定 验 讶 


方法 。 它 的 值 为 以 下 4 种 中 的 一 个 : BASIC、DIGEST、FO 


旨 定 验 证 中 使 用 的 


领域 名 。 


2) realm-name: realm-name: 


来 标识 在 客户 端 和 Web 容 器 之 间 传 输 数据 的 方式 。transport-guarantee 元 素 必须 
在 传送 中 不 能 改变 ; CONFIDENTIAL， 意 味 着 传输 的 数据 必须 是 加 密 的 数据 。 通 常 ，TLS 使 


有 如 下 的 某 个 值 : NONE， 意 味 着 应 用 不 需要 传输 保证 ; 
INTEGRAL 或 CONFIDENTIAL。 


RM 或 CLIENT-CERT。 


3) form-login-config: form-login-config 指 定 基于 表单 认证 的 登录 中 使 用 的 登录 页 面 和 登录 失败 页 面 。 如 果 没 有 使 用 基于 表 
资源 路 径 ，form-error-page 则 用 于 指定 用 户 登 录 失 败 时 显示 出 错 页 面 的 资源 路 径 。 


<login-config> 
<auth-method>FORM</auth-method> 
<form-login-config> 
<form-login-page>/login.html</form-login-page> 
<form-error-page>/error.html</form-error-page> 
</form-login-config> 
</login-config> 


(3) secutity-role 元 素 
security-role 元 素 指定 用 于 安全 约束 中 的 安全 角色 的 声明 。role-name 指 定 角色 名 称 。 


<security-role> 
<role-name>admin</role-name> 
</security-role> 
<security-role> 
<role-name>user</role-name> 
</security-role> 


6.2.2 ”应 用 管理 权限 


相对 于 容器 管理 权限 ， 应 各 自 通过 编码 和 注 


管理 权限 是 指 容器 中 的 每 个 应 


(1) JSR 250 


JSR 250 (Common Annotations for the Java Platform 1.1，Java 平 台 通 


义 ， 实 现 权限 管理 。 


注解 @PermitAll、@DenyAll 和 @RolesAllowed 用 来 定义 方法 级 别 的 访问 权 
@RolesAllowed 注 解 定义 的 方法 允许 指定 的 角色 访问 。 如 果 注 解 在 类 级 别 ， 适 


注解 @DeclareRoles 和 @RunAs 


来 定义 类 级 别 的 访问 权限 。 


注解 @RunAs 定 义 的 方法 允许 执行 


定义 。 


的 角色 必须 存在 了 户 或 组 。 注 解 @Declare 


安全 领域 中 ， 并 映射 型 


<security-role> 
<role-name>admin</role-name> 
</security-role> 


(2) JAX-RS 2.0 


恨 。 使 用 @ DenyAll 注 解 定 义 的 方法 不 允许 任何 角色 访问 。 使 
于 类 中 所 有 的 方法 。 如 果 注 解 在 方法 级 别 ， 则 方法 级 别 的 权限 注解 优先 于 /覆盖 类 级 别 的 权限 注解 。 


于 指定 显示 登录 页 面 的 


的 验证 ， 则 忽略 这 些 元 素 。form-login-page 


解 完 成 对 资源 路 径 访问 的 权限 管理 。 


注解 标准 ) 提供 了 安全 访问 注解 ， 包 名 为 javax.annotation.security。 应 用 代码 通过 使 用 安全 访问 注解 对 资源 路 径 进 行 定 


@PermitAll 注 解 定义 的 方法 允许 所 有 角色 访问 。 使 F 


来 定义 允许 执行 该 类 的 安全 角色 。@ DeclareRoles (“admin”) 相当 于 如 下 的 XML 格式 


Rolesf 


JAX-RS 2.0 规 范 定 义 了 一 个 安全 上 下 文 接口 


SecurityContext， 通 过 该 接 


的 实现 可 以 在 运行 时 获取 当前 


户 的 身份 信息 ， 从 而 通过 编码 方式 ， 动 态 地 为 当前 


户 提 供 资 源 访问 的 权限 。 


Jersey 2.x 提 供 了 DynamicFeature 接 口 的 实现 类 RolesAllowedDynamicFeature，REST 服 务 或 应 
作 原 理 是 REST 应 用 使 用 注册 的 RolesAllowedDynamicFeature 从 SecurityContext.isUserlnRole() 获 取 
403) 给 客 


户 端 。 


6.3 ”认证 与 授权 实现 


前 面 两 节 分 别 讲述 了 认证 和 授权 的 方式 ， 本 节 将 结合 不 同 的 认证 和 授权 方式 ， 为 读者 呈现 5 种 实现 。 


全 阅读 指导 6.3 节 示例 所 在 目录 是 : jax-rs2-guide\sample\6\security-rest。 


通过 注册 该 类 即 可 使 
户 角 色 并 和 类 以 及 方法 中 使 


JSR 250 的 注解 和 JAX-RS 2.0 的 SecurityContext 动 态 管理 资源 访问 权限 。 其 工 
的 JSR 250 注 解 匹 配 ， 如 果 失 败 ， 即 返回 没有 权限 的 错误 (HTTP 状态 码 


源 代 码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/6/security-rest 


6.3.1 ”基本 认证 与 JDBCRealm 


本 示例 使 用 HTTP 基 本 认证 ,结合 Tomcat 提 供 的 JDBCRealm 实 现 认 证 与 授权 。 本 例 所 示 的 场景 为 以 webapi/ 开 头 的 资源 路 径 需 要 用 户 登录 访问 。 其 中 获取 | 


中 | 


书 列表 的 只 读 资 源 路 径 


(http://localhost:8080/security-rest/webapi/books) 可 以 被 admin 角 色 和 user 角 色 访 问 ， 其 他 以 webapi/ 开 头 的 资源 路 径 只 有 admin 角 色 可 以 访问 。 


小 白 讲 堂 


Realm 的 概念 在 6.2.1 节 已 经 介绍 过 ， 有 关 Tomcat 的 Realm 详 情 可 参考 官方 文档 ， 地 址 是 : http://tomcat.apache.org/tomcat-7.0-doc/realm-howto.html。 


(1) 创建 Realm 所 需 的 数据 表 


JDBCRealm 通 过 JDBC 访 问 关系 型 数据 库 获取 认证 信息 ， 首 先 我 们 从 数据 库 脚本 入 手 ， 逐 步 完 成 认证 与 授权 的 实现 。 本 例 使 用 MySQl 数 据 库 ， 脚 本 信息 如 下 。 


导出 数据 库 脚本 的 命令 为 : mysqldump simpleservicebook -uroot -P security.sql 
// 
导入 数据 库 脚本 的 命令 为 : mysql -uroot -p < security.sql 


DROP DATABASE IF EXISTS ‘simple service book 
CREATE DATABASE ‘simple service book’; 
USE ‘simple service book’; 
CREATE TABLE ‘simple book. 
( 
“BOOKID. int 
Ci 
) NOT NULL AUTO INCREMENT, 
“BOOKNAME varchar 
(128 
) DEFAULT NULL, 
“PUBLISHER ”Varchar 
(128 
) DEFAULT NULL, 
PRIMARY KEY 
(`BOOKID、 
) ， 
UNIQUE KEY “BOOKID、 
(`BOOKID、 
) 


) ENGINE=InnoDB DEFAULT CHARSET=utf87 

LOCK TABLES ‘simple book” WRITE; 

INSERT INTO ‘simple book. VALUES 
(1,'Java Restful Web Service 

使 用 指南 '，'cmpbook"' 

) 


(2, 'JSF2 
和 RichFaces4 
使 用 指南 '，'phei' 
和 


UNLOCK TABLES; 
CREATE TABLE ‘user roles. 
( 
‘user name. varchar 
(15 
) NOT NULL, 
‘role name. varchar 
(is 
) NOT NULL, 
PRIMARY KEY 
(‘user name', ‘role name. 
) 
) ENGINE=InnoDB DEFAULT CHARSET=utf8; 
LOCK TABLES ‘user roles ”WRITE; 
INSERT INTO ‘user roles. VALUES 
('caroline', 'user' 
) ， 
(eric' 'admin' 
汪汪 
UNLOCK TABLES; 
CREATE TABLE ‘users. 
( 
‘user name. varchar 
人 8 
) NOT NULL, 
‘user Pass ”Varchar 
CLS 一 
) NOT NULL, 
PRIMARY KEY 
(user_name 
) 
) ENGINE=InnoDB DEFAULT CHARSET=utf8; 
LOCK TABLES ‘users. WRITE; 
INSERT INTO ‘users. VALUES 
('caroline', 'zhang' 


’ 
('eric', 'han' 
); 

UNLOCK TABLES; 


亚 


这 段 


本 创建 了 名 为 simple_service_book 的 数据 库 ， 该 数据 库 包 含 名 为 simple_book 的 表 用 来 展示 REST 请 求 资源 ， 另 外 ， 名 为 user_roles 的 表 和 名 为 users 的 表 用 来 展示 JDBCRealm 认 证 和 授权 。 本 例 


包含 两 个 用 户 ， 一 个 是 角色 为 admin 的 eric 用 户 ， 另 一 个 是 角色 为 user 的 caroline 用 户 。 认 证 通过 后 ， 根 据 两 个 用 户 具有 的 身份 不 同 ， 将 会 有 不 同 的 权限 。 


(2) 配置 JDBCRealm 


根据 Tomcat 官 方 网 站 提供 的 文档 (http://tomcat.apache.org/tomcat-7.0-doc/config/realm.html) ， 服 务 器 配置 文件 $CATALINA_BASE/conf/server.xml 设 置 如 下 所 示 。 


<Realm className="org.apache.catalina.realm.JDBCRealm" 

driverName="org.gjt.mm.mysqgl .Driver" 

connectionURI="jdbc:mysql://localhost:3306/simple service book?user=root&amp;password=root" 
userTable="users" 

userNameCol="user name" 

userCredCol="user pass" 

userRoleTable="user roles" 

roleNameCol="role name"/> 


在 这 段 脚 本 中 ， 用 户 表 为 users， 用 户 名 字段 为 user_name， 密 码 字 段 为 user_pass; 角色 表 为 user_roles， 角 色 名 字段 为 role_name。 


$CATALINA_BASE 路 径 可 以 是 Tomcat 的 物理 路 径 ， 也 可 以 是 IDE 集 成 环境 中 的 相对 路 径 。 更 灵活 的 设置 方式 是 使 
Eclipse 为 例 ， 在 Servers 实 例 的 内 置 Tomcat 中 ， 配 置 serverxml 文 件 ， 如 图 6-1 所 示 。 


后 者 ， 即 在 IDE 集 成 环境 中 对 服务 器 配置 ， 以 方便 切换 不 同 配置 和 断 点 调试 。 以 


File 
i 器 - 回 史 久 | 妆 -O-Q@%- 电台- | 外 由 妨 - 瑟 司 区 -别人 人 -号 > 


全 BE /BT 二 日 ] 网 serverxml 器 


互 图 | 留 了 1 <2xml version="1.9”encoding="UTF-8"?> 
= 28l<Serverl port=" 8995” shutdown="SHUTDOWN™> 
4 BB Severs <[Listener SSLEngine="on” className="org.apache.catalina.core.AprLifecyclelistener” /> 
< BS Tomcat v70 Serverat! <Listener crassname= "rg.apactie.cavarina.core.JasperListener™ /$ 
加 catalina.policy <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener” /> 
十 catalina.properties <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"” /> 
context xml AETET TUS MMe EH dinm nt "hn ed udlcell revrati niriaa" 
= <GlobalNamingResources> 
<Resource auth="Container” description="User database that can be updated and saved” 
factory="org.apache.catalina.users.MemoryUserDatabaseFactory” name="UserDatabase” 
四 webxml pathname="conf/tomcat-users.xm]l” type="org.apache.catalina.UserDatabase” /> 
</GlobalNamingResources> 
name="Catalina”> 
<Connector connectionTimeout="2880880” port="8889”" protocol="HTTP/1.1" 
redirectPort="8443” /> 
<Connector port="8889" protocol="AJP/1.3” redirectPort="8443" /> 
EEnEInel detaultHost="1localhost" name="Catalina”> 


I tomcat-users.xml 


<Realm className="org.apache.catalina.realm.JDBCRealm" driverName="org.gjt.mm.mysql.Driver” 
connectionURL="jdbc:mysql://localhost:3386/sinple service book?user=root&amp;password=root” 
userTable="users” userNameCol="user name™” userCredCol="user pass” 
userRoleTable="user roles” roleNameCol="role name™” /> 


KHostl appBase="webapps” autoDeploy="true” name="localhost” unpackWARs="true”"> 
docBase="security-rest” path="/security-rest” reloadable="true” 
source="org.eclipse.jst.j2ee.server:security-rest” /> 
</Host> 
</Engine> 
28 </Service> 
畏 29 </Server> 


| 


图 6-1 Eclipse 中 定义 Tomcat 配 置 示 意 
(3) 数据 库 驱 动 


复制 MySQL 的 JDBC 驱 动 到 $CATALINA_HOME/lib 目 录 。 使 用 Maven 的 项 目 可 以 从 本 地 仓库 获取 ， 否 则 可 以 网 上 搜索 。 本 地 仓库 地 址 为 M2_REPO/mysql/mysql-connector-java/5.1.25/mysql- 
connector-java-5.1.25.jar (仓库 地 址 路 径 示 例 : M2_REPO=C:\Users\hanl\.m2\repository) 。 


(4) 配置 应 用 


Web 配 置 文件 /security-rest/src/main/webapp/WEB-INF/web.xml 摘 要 如 下 ， 逻 辑 如 前 所 述 。 


<security-constraint> 
<web-resource-collection> 
<url-pattern>/webapi/*</url-pattern> 
<http-method>GET</http-method> 
<http-method>POST</http-method> 
<http-method>UPDATE</http-method> 
<http-method>DELETE</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>admin</role-name> 
</auth-constraint> 
</security-constraint> 
<security-constraint> 
<web-resource-collection> 
<url-pattern>/webapi/*</url-pattern> 
<http-method>GET</http-method> 
</web-resource-collection> 
<auth-constraint> 
<role-name>user</role-name> 
</auth-constraint> 
</security-constraint> 
<login-config> 
<auth-method>BASIC</auth-method> 
</login-config> 


Tomcat 将 调用 Realm.authenticate0 对 首次 访问 的 用 户 进行 认证 。 认 证 通过 后 被 缓存 在 Tomcat 容 器 内 。 缓 存 失效 的 策略 是 ， 对 于 表单 认证 ， 直 到 session 失 效 ， 而 对 于 基本 认证 ， 直 到 关闭 浏览 器 。 


(5) 认证 和 授权 测试 


启动 本 节 示 例 的 服务 ， 使 用 如 下 测试 用 例 逐 步 测试 和 理解 本 例 对 认证 和 授权 的 实现 。 测 试用 例 1 的 说 明 见 表 6-2， 直 接 访问 图 书 列表 资源 地 址 而 不 提供 用 户 身份 信息 。 


表 6-2 基本 认证 测试 用 例 1 说 明 


测试 要 素 说 明 
测试 工具 Chrome 插件 Postman (参考 2.6 节 中 的 REST 调试 工具 ) 
测试 地 址 http://localhost:8080/security-rest/webapi/books 
测试 方法 GET 
测试 用 户 无 
测试 结果 401 Unauthorized 


服务 器 返回 HTTP 状 态 码 401， 如 图 6-2 所 示 ， 进 入 质询 /回应 的 对 话 流程 ， 流 程 参见 后 续 测试 用 例 。 


http://localhost:-8080/security-rest/webapi/books 


Preview Add to collection 
Headers (7) EE 401 Unauthorized NRL 26 ms 


Cache-Control> private 
Content-Length > 951 

Content-Type > text/htmtl:charset=utf-8 
Date > Wed, 11 Sep 2013 10:23:19 GMT 
Expires > Thu, 01 Jan 1970 08:00:00 CST 


Server> Apache-Coyote/1.1 
WWW-Authenticate > Basicrealm="Authentication required" 


6-2 ”基本 认证 测试 用 例 1 结果 


测试 用 例 2 的 说 明 见 表 6-3， 使 用 基本 认证 并 设置 用 户 为 caroline 来 访问 图 书 列表 资源 地 址 。 


表 6-3 ”基本 认证 测试 用 例 2 说 明 


测试 要 素 说 明 
测试 工具 Chrome 插件 Postman 
测试 地 址 http://localhost:8080/security-rest/webapi/books 
测试 方法 GET 
测试 用 户 caroline role=user 
测试 结果 200 OK 


服务 器 通过 认证 ， 因 为 GET 方 法 只 读 资 源 授权 给 user 用 户 ， 返 回 HTTP 状 态 码 为 200 和 图 书 列表 资源 表述 ， 如 图 6-3 所 示 。 


Normal | BasicAuth | Digest Auth | OAuth1.0 | < Noenvironmentv 


http://localhost:8080/security-rest/Wwebapi/books GET 加 | CURLparams Cg Headers (1) 


Authorization Basic Y2Fyb2xpbmU6emhhbmc= [x) Add preset 


Manage presets 


Header Value 


Send Preview Add to collection 


Body | Headers( ] EDQ2ook TIME EYL9 


Pretty | Raw | Preview La | 让 | JSON | XML 


1 <?xml] version="1.0" encoding="UTF-8” standalone="yes"?> 

2 <books> 

3 <bookList> 

4 <book bookId="1”bookName="Java Restful Web service 使 用 指南 ”publisher="cmpbook"/> 
5 <book bookId="2”bookName="JSF2 和 RichFaces4 使 用 指南 ”pub1lisher="phei"/> 
6 <“/bookList> 
7 </books> 


图 6-3 ”基本 认证 测试 用 例 2 结 果 


试用 例 3 的 说 明 见 表 6-4， 使 


党 
避 


测试 要 素 


测试 工具 
测试 地 址 
测试 方法 
测试 用 户 
测试 结果 


服务 器 未 通过 认证 ， 因 为 创建 新 图 


BasicAuth 


用 基本 认证 并 设置 用 户 为 caroline 来 访问 创建 新 图 书 的 资源 地 址 。 


表 6-4 基本 认证 测试 用 例 3 说 明 
说 明 
Chrome 插件 Postman 
http://localhost:8080/security-rest/webapi/books 
POST 
caroline role=user 
403 Forbidden 


书 的 资源 地 址 只 授权 给 admin 用 户 ， 返 回 HTTP 状 态 码 为 403， 请 求 被 禁止 ， 如 图 6-4 所 示 。 


< Noenvironmentv 


http-WIocalhost-8080/security-restiwebapibooks 


Authorization 


Header 


Basic Y2Fyb2xpbmU6emhhbmc= 


Value 


form-data 


Key 


x-www-form-urlencoded raw binary 


Value 


Preview Add to collection 


Headers (4) 


Content-Length 3 1057 


EU 403 Forbidden NR 39 ms 


Content-Type > text/html:charset=utf-8 


Date > Wed, 11 Sep 2013 10:34:31 GMT 


Server > Apache-Coyote/1.1 


图 6-4 ”基本 认证 测试 用 例 3 结果 


测试 用 例 4 的 说 明 见 表 6-5， 使 用 基本 认证 并 设置 用 户 为 eric 来 访问 创建 新 图 书 的 资源 地 址 。 


测试 要 素 


测试 工具 
测试 地 址 
测试 方法 
测试 用 户 
测试 结果 


服务 器 通过 认证 ， 因 为 创建 新 图 书 的 资源 地 址 授权 给 admin 


表 6-5 基本 认证 测试 用 例 4 说 明 


说 明 
Chrome 插件 Postman 
http://localhost:8080/security-rest/webapi/books 
POST 
eric role=admin 
200 OK 


用 户 ， 返 回 HTTP 状 态 码 为 200 和 创建 完毕 的 新 图 书 资源 表述 ， 如 图 6-5 所 示 。 


Normal Digest Auth OAuth 1.0 < Noenvironmentv 


http://localhost:8080/security-rest/webapi/books 


Authorization Basic ZXJpYzpoYW4= 


Content-Type application/xml 


form-data | x-www-form-urlencoded am | binary | XML(application/xml) Y 


1 <book bookName="sonarQube 使 用 指南 ”publisher="MARS"/> 


Send Y Preview Add to collection 


Body | Headers(4) STATUS 200 OK TIME Ex 和 


| Pretty | Raw | Preview 本 JsoN | XML | 


1 <?xml version="1.60" encoding="UTF-8"” standalone="yes"3?3> 
2 <book bookId="3”bookName="sonarQube 使 用 指南 ”publisher="MARS"/> 


图 6-5 ”基本 认证 测试 用 例 4 结果 


到 此 ， 我 们 通过 4 个 测试 用 例 对 示例 的 场景 进行 了 覆盖 性 的 功能 测试 ， 本 示例 如 预期 完成 了 既定 功能 。 最 后 ， 通 过 断 点 调试 了 解 一 下 omcat 是 如 何 使 用 JDBCRealm 完 成 HTTP 基 本 认证 功能 的 。 


(6) 基本 认证 


Ow 本 例 使 用 的 Tomcat 版 本 为 7.0.42，Maven 仓 库 源 代码 地 址 为 C:\Users\hanl.m2\repository\org\apache\tomcat\tomcat-catalina\7.0.42\tomcat-catalina-7.0.42-sources.jar。 


以 Debug 的 方式 在 IDE 中 启动 本 示例 ， 并 使 用 上 述 的 “测试 用 例 4” 向 服务 器 发 出 请 求 。 如 图 6-6 所 示 ， 通 过 断 点 的 栈 信息 可 以 看 到 ，JDBCRealm 类 的 authenticate( 方 法 最 终 处 理 客户 端 请 求 信息 和 数 


据 库 身份 信息 的 匹配 工作 。 


滨 咏 虽 国 小 | 人 RR 纪 | 式 | 针 ” 


pS Daemon Thread [http-bio-8080-exec-6] (Running) 
只 Daemon Thread [http-bio-8080-exec-8] (Suspended) 

Eg JDBCRealm.authenticate(Connection, String, String) line: 433 
JDBCRealm.authenticate(String, String) line: 355 
BasicAuthenticator.authenticate(Request, HttpServletResponse, 
BasicAuthenticator(AuthenticatorBase).invoke(Request, Respon 
StandardHostValve.invoke(Request, Response) line: 171 
ErrorReportValve.invoke(Request, Response) line: 99 
StandardEngineValve.invoke(Request, Response) line: 118 
CoyoteAdapter.service(Request, Response) line: 408 


MY AY IN IN 


// Create and return a suitable Principal for this user 
return (new GenericPrincipal(username, credentials, roles)); 


兴 


this 
dbConnection 
Username 
credentials 
dbCredentials 
validated 


Value 


JDBCRealm (id=57) 


JDBC4Connection (id=82) 
“eric (id=58) 

"han" (i d=63) 

"han" (id=92) 

true 

ArrayList<E> (id=93) 


图 6-6 JDBCRealm 类 处 理 基本 认证 


客户 端 请 求 信息 中 用 户 名 和 密码 的 解析 是 在 基本 认证 BasicAuthenticator 类 的 authenticate() 方 法 中 完成 的 ， 如 图 6-7 所 示 ， 该 方法 按照 base64 (username:password) 的 格式 对 字符 串 进行 了 解码 。 


蓄 Debug 器 和 师 Servers 各 Type Hierarchy TG WVariables 吕 se Breakpoints Of Expressions 
流 咕 吕 国 症 | 叉 及. 此 去 | 允 | 旬 了 Value 


bp Daemon Thread [Abandoned connection cleanup thread] (Running) 四 this BasicAuthenticator 
WW Daemon Thread [http-bio-8080-exec-9] (Running) decoded lid=370) 
no Daemon Thread [http-bio-8080-exec-10] (Suspended) colon 4 
三 BasicAuthenticatorauthenticate(Request HttpSemvletResponse, LoginConfi authorizationBC ByteChunk (id=372 
BasicAuthenticator[AuthenticatorBase).invoke(Request, Response) line: 574 recjuest Request (id=111) 
StandardHosiValve.invoke(Request, Response) line: 171 response Response (id=115) 
ErrorReportValve.invoke(Request, Response) line: 99 config LognConfig (id=1 
StandardEngincVYalve,invokc(Requecst, Response) Inc 118 principal null 
CuyulcAdYaplciscivicc(Reygucst Respvunsc) linc 408 
HttplliProcessoi(AbstractHttpllProcessor<3>).process(SocketWirapper< 5> 
HttpllProtocolS$Httpll ConnectionHandler(AbstractProtocol$AbstractConr 
JioEndpoint$SocketProcessor.run(Q line 312 
ThreadPoolExecutor(ThreadPoolExecutor).runWorker(ThreadPoolExecutor$ 
ThreadPoolExecutorS$Worker.run( line: 615 

三 TaskThread(Thread),run( line 724 
Di\Program Files\Java\jdk],7,)_25\bin\javaw,exe (Sep 13, 2013 41725 PM) 


>>uly null 

Username "efic" (id=378) 
password "han” (id=379) 
authorization MessageBytes (id= 


GeGeoeeDGDGGSIe 


114，1695，99，58，104，97，119] 


if (colon < 0) { 
username = new String(decoded, B2CConverter.ISO 8859 1); 
} else { 
username = new String( 
decoded, 8, colon, B2CConverter.ISO 8859 1); 
password -~ new String( 
decoded, colon + 1, decoded.length - colon - 1, 
B2CConverter. ISO 8859 1)， 


图 6-7 BasicAuthenticator 类 的 authenticate0 方 法 


最 后 ， 如 图 6-8 所 示 ，BasicAuthenticator 类 的 invoke() 方 法 对 响应 头 进行 了 修改 。 


| 芝 Debug 器 习 山 Servers| 各 TypeHierarchy| 23 99 Breakpoints| ed Expressions 


演 咏 四国 沾 |3. 翁 . 

史 Daemon Thread [http-bio-8080-exec-7] (Running) 

史 Daemon Thread [http-bio-8080-exec-6] (Running) 

bs Dacmon Thread [http-bioc-8080-exec-8 (Running] 

pS Daemon Thread [Abandoned connection cleanup thread] (Running) 

哈 Daemon Thread [http-bio.-8080-exec-9] (Running] 

只 Daemon Thread [hrtp-bio-3080-exEc-10] (Suspended (breakpoint at line S17 
三 Request, Response) line: 5 
三 StandardHostYalve.invoke(Request, Response) line; 171 
三 ErroReportyValve,invoke(Request, Response) line 99 E 
三 SandardEngineValveinvoke(Request Response) line: 118 
云 CoyoteAdapter.service(Request, Response) line: 408 
过 HttpllProcessor(Mbst ractHttpllprocessor<5>),process[SocketW rapper« 
去 HttpllProtocolSHttpliConnectionHandler(AbstractProtocol$SAbstractCo 


到 
a 


Valuec 

this BasicAuthenticator 人 id=69) 
request Request (i:d=278} 
response Response (id=279) 
config LoginConfig (1d=119) 
contextPath “Jsecurity-rest" (id=121) 
requestURI “Jsecurity-rest/webapi” [id=222) 
SESSION null 
Wrapper standardWrapper (1d=126] 

realm JDBCRealm (id=57) 
constroints SecurityConstraint[2] (1d=283] 


O00@0ee@o@e@ee 


| 三 JoEndpointSSocketprocessorrunl line 312 
4 om ed 


ty JDBCRealm.class 1 AuthenticatorBase,class % 


/i Make sure that constrained resources are not cached by web proxies 


/i or browsers as caching can provide a security hole 
if (constraints !- null 8&8 disableProxyCaching && 
1"POST" .equalslgnoreCLase(request.getMethod())) { 


: These can cause problems with downloading files with IE 
response. setHeader ("Pragma", "No-cache"); 
response. setHeader ("Cache-Control”, "no-cache™); 

} else { 
response.setHeader("Cache-Control”, "private"),; 
} 


response. setHeader(“Expires”, DATE ONE); 


4 WW DATEONE= 'Thu DiJon1970D8:00:00 CST" [id=20| | 


图 6-8 ”BasicAuthenticator 类 的 invoke0 方 法 


6.3.2 ”摘要 认证 与 UserDatabaseRealm 


本 示例 使 用 HTTP 摘 要 认证 结合 Tomcat 提 供 的 UserDatabaseRealm 实 现 认证 与 授权 。 为 了 简化 示例 逻辑 ， 本 例 所 示 的 授权 场景 和 前 例 基 本 相同 ， 不 同 的 是 ，UserDatabaseRealm 通 过 读 取 XML 格式 的 
JNDI 资 源 (默认 使 用 conf/tomcat-users.xml) ， 获 取 认 证 信息 。 因 此 本 例 不 需要 数据 库 的 支持 。 


(1) 配置 UserDatabaseRealm 


同 前 例 ， 服 务 器 配置 文件 $CATALINA_BASE/conf/server.xml 添 加 Realm ， 其 资源 通过 名 称 匹 配 在 Resource 中 定义 的 XML 文件 。 


<Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="tom" /> 
<Resource auth="Container" description="User database that can be Updated and 

saved" factory="org.apache.catalina.users.MemoryUserDatabaseFactory" 

name="tom" pathname="conf/tomcat-users.xml" type="org.apache.catalina.UserDatabase" /> 


同 前 例 ，Eclipse 内 置 的 Tomcat 配 置 如 图 6-9 所 示 。 


图 Jaa- Severs/Tom 


File Edit Source Navigate Search Project Run Window Help 


因 岛 ; 历 "Orv@%r :者 (C A 


:SBF 


有 其 "市" 中心 


( 国 pac_ 3\ JJun| RE 所 


日 图 | > 
这 > security-rest [jax-rs2-guide maste! 
人 攻 Servers 
EE Tomcat v7.0 Server at localhost- 
团 catalina.policy 


wp 


国 catalina.properties 
放 context.xml 

I tomcat-users.xml 
四 webxml 


NO 加 


Bb bd be 
w bpag@gw 


= 
NO 人 


W 和 


N 


oo 
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wD 


加 tomcat-usersxml 


rsion="1.9”encoding="UTF-8” ?2 
port="80805” shutdown="SHUTDOWN"> 
on” className="org.apache.catalina.core.AprlifecyclelListener” /> 


<Listener SSLEngine=" 
<Listener className=" 
<Listener className=" 
<Listener className=" 
<Listener className="™ 


org.apache. 
org.apache. 
org.apache. 
org.apache. 


<GlobalNamineResources> 


catalina. 
catalina. 
catalina. 
catalina. 


core.JasperListener” /> 
core.JreMemoryLeakPreventionListener” /> 
mbeans .GlobalResourcesLifecyclelistener” /> 
core.ThreadLocalLeakPreventionListener” /> 


factory="org.apache.catalina.users.MemoryUserDatabaseFactory” name="tom" 
pathname="conf/tomcat-users.xml” type="org.apache.catalina.UserDatabase” /> 


name="Catalina”"> 


<Connector connectionTimeout= "206096”port= " 59859”protocol= "HTTP/I.I” 
redirectPort="8443” /> 


Kenaine]defaultHost=" localhost" name="Catalina"> 


ealm.UserDatabaseRealm” 


I<Host ppBase= "webapps”autoDeploy= "true”name= "localhost”unpackWARs= true "> 
[Context HocBase= "security-rest”path="/security-rest”reloadable= "true” 
source="org.eclipse,.jst.j2ee.server:security-rest” /> 


</Host> 
</Engine> 


</Service> 
</Server> 


图 6-9 ”在 Eclipse 中 为 Tomcat 插 件 配置 Realm 


Resource 中 定义 的 XML 文件 为 $CATALINA_BASE/conf/tomcat-users.xml， 按 照 前 述 的 逻辑 ， 定 义 如 下 。 


<?xml Version="1.0" encoding="UTF-8"?> 
<tomcat-userS> 
<role rolename="admin" /> 
<role rolename="user" /> 
<user name="eric" password="han" roles="admin" /> 
<user name="caroline" password="zhang" roles="user" /> 
</tomcat-users> 


Eclipse 内 置 Tomcat tomcat-users 配 置 如 图 6-10 所 示 。 


殉 


Y mh 


日 图 8 > 
Fa 


Ey > Security-rest [jax-rs2-guide mastel 


这 Servers 


蕊 Tomcat v7.0 Server at localhost- 
图 catalina.policy 
国 catalina.properties 
网 contextxml 
0 serverxmnl 


(2) 配置 应 用 


1 《<《?xml version="1.9”encoding="UTF-8”?> 


2 已 <tomcat- 
<role 
<role 
<USer 
<user 

</tomcat-users> 


DooNnwm WwW 


Ppppp 
Dp 


USers> 


图 6-10 ”在 Eclipse 中 为 Tomcat 插 件 配置 用 户 权 限 


同 前 例 ， 配 置 /security-rest/src/main/webapp/WEB-INF/web.xml 文 件 。 注 意 ， 此 处 省 略 相同 部 分 。 


rolename="admin” /> 

rolename="user™” /> 

name="eric” password="han” roles="admin”" /> 
name="caroline™” password="zhang” roles="user” /> 


<login-config> 
<auth-method>DIGEST</auth-method> 
<realm-name>drealm</realm-name> 
</login-config> 


(3) 认证 和 授权 测试 


摘要 认证 与 基本 认证 的 算法 不 同 ， 但 呈现 方式 相同 ， 都 是 弹出 窗口 ， 让 用 户 输入 用 户 名 和 密码 。 由 于 本 例 的 测试 用 例 和 前 例 相同 ， 因 此 不 再 歼 述 ， 在 此 只 讲述 digest 请 求 信息 的 相关 元 素 。 如 图 6-11 所 
示 ， 在 使 用 用 户 eric 访 问 图 书 列表 的 请 求 头 中 ， 包 含 了 摘要 认证 的 全 部 元 素 ， 详 细 分 析 见 表 6-6。 


名 | Clear Persist |[ AI] HIML Css Javascript XHR Images Plugins Media Fonts 
ete ee ae Re te fee Ee 


已 GET books 253B  [::J]:8080 


Headers Response XML Cache 


private 

253 

application/xml 

Thu, 17 Oct 2013 08:47:18 GMT 
Thu, O01 Jan 1970 08:00:00 CST 
Apache-Coyote/1.1 


ew SOUrCe 


text/html, application/xhtmli+xml,application/xml;q=0.9,*/*;q=0.8 

gzip, deflate 

en-US,en;q=0.5 

Digest username="eric", realm="drealm", nonce="1381999633918:ffc415c1i0bd6811c945d37e923f8£223", uri=" 

/security-rest/webapi/books", response="a20adS8ed040f72340832985a2725918e", opaque="2CE4AM1498BS5SAASICDOSESA6E1BEATEAF" 
qop=auth, nc=00000001, cnonce="82bab21911e381e7" 


keep-alive 
localhost:8080 
Mozilla/5-0 (Windows NT 6-17 WOWE€4; rv:24.0) Gecko/20100101 Firefox/24.0 


图 6-11 摘要 认证 头 信息 
表 6-6 摘要 认证 参数 列表 


认证 条 目 简 述 


username="eric" 用 户 名 

realm="drealm" Realm 名 称 
nonce="1381999633918:ffc415c10bd6811c945d37e923f8f223" 服务 器 端 随机 数 
uri="/security-rest/webapi/books" REST 服务 资源 地 址 
response="a20ad8ed040f72340832985a2725918e" MD5 (HAl:nonce:HA2 ) 计算 值 
opaque="2CE4A149B55A859CD05E58661BEA768F" 服务 器 端 质询 响应 信息 


qop=auth 保护 质量 
nc=00000001 客户 端 请 求 计数 器 
cnonce="82bab21911e381e7" 客户 端 随机 数 


(4) 摘要 认证 


如 图 6-12 所 示 ， 通 过 断 点 栈 可 以 观察 到 ，UserDatabaseRealm 类 的 authenticate() 方 法 完成 了 摘要 认证 的 算法 ， 具 体 为 
md5 (md5 (username:realm:password) :nonce:nc:cnonce:qop:md5 (httpmethod:uri) ) 。 可 参考 摘要 认证 类 DigestAuthenticator。 


葛 Debug 33 、、 岗 Severs| 用 Type Hierarchy， 


滨 吃 昌国 下 |3. 人 人 人 纠 | 式 | 贸 


pS Daemon Thread [http-bio-8080-exec-3] (Running) 
pS Daemon Thread [http-bio-8080-exec-4] (Running) 


只 Daemon Thread [http-bio-8080-exec-5] (Suspended) 


UserDatabaseRealm(RealmBase).authenticate(Strinc 
DigestAuthenticator$Digestinfo.authenticate(Realm 
DigestAuthenticator.authenticate(Request, HttpSer, 
DigestAuthenticator(AuthenticatorBase).invoke(Rec 
StandardHostValve.invoke(Request, Response) line: 
ErrorReportValve.invoke(Request, Response) line: 99 


之 


a 


(= Variables 只 


到 
E 


SoBreakpoints Hf pressions] 


Value 


UserDatabaseRealm (id=51) 

"eric" (id=59) 

"6fe4b2af69ecaebf09862d338e91ea63" (id=64) 
"1379057444423:03ae2e93a66bb2fd61835f0492d5fd27" 
"00000001" (id=69) 

"c4b3231d4ccc3d8a" (id=70) 

"auth" (id=72) 

"drealm" (id=73) 
"92f0ab3cd3b204d40512b4714d42e254" (id=74) 


"d4b43732cbalc0b300eb788af93f0a63" (id=125) 
"d4b43732cbalc0b300eb788af93f0a631379057444423; 
(id=129) 

"6fe4b2af69ecaebf09862d338e91ea63" (id=130) 


StandardEngineValve.invoke(Request, Response) lin 
CoyoteAdapter,service(Request, Response) line: 408 
HttpllProcessor(AbstractHttpllProcessor<S>).pro' 
HttpllProtocol$HttpllConnectionHandler(Abstrac 
JloEndpoint$SocketProcessor.run( line: 312 

三 ThreadPoolExecutor(ThreadPoolExecutor).runWork 


三 ThreadPoolExecutor$Worker.run( line: 615 
| 


serverDigestValue 


valueBytes 
serverDigest 


@O@@0@0@0@0@0@0@e@e@ee 


6fe4b2af69ecaebf09862d338e91ea63 
6fe4b2af69ecaebf09862d338e91ea63 


" 四 


”+ nc + ”cnonce:”+ cnonce + " 
realm:”+ realm + “md5a2:™ + md5a2 
+ ”Server digest:”+ serverDigest); 


qop:”+ qop 


if (serverDigest.equals(clientDigest)) { 
return getPrincipal(username); 


图 6-12 ”UserDatabaseRealm 类 的 authenticate( 方法 
6.3.3 ”表单 认证 与 DataSourceRealm 


本 示例 使 用 表单 认证 ， 并 结合 Tomcat 提 供 的 DataSourceRealm 类 实现 认证 与 授权 。 为 了 简化 示例 逻辑 ， 本 例 所 示 的 授权 场景 和 前 例 相 同 。DataSourceRealm 通 过 JNDI 访 问 关系 型 数据 库 ， 获 取 认证 
信息 。DataSourceRealm 与 UserDatabaseRealm 相 比 ， 数 据 库 连接 使 用 容器 提供 的 全 局 数据 源 (Data Source) ， 而 不 是 在 Realm 中 自行 配置 。 


我 们 首先 需要 创建 Realm 所 需 的 数据 表 ， 同 6.3.1 节 的 数据 库 脚 本 ,使 用 “mysql-uroot-p<security.sql” 命 令 导入 。 


(1) 配置 DataSourceRealm 


同 前 例 ， 服 务 器 配置 文件 $4CATALINA_BASE/conf/server.xm| 添 加 Realm， 首 先 配置 容器 的 全 局 数据 源 。 


<Resource auth="Container" 
driverClassName="org.gjt.mm.mysql .Driver"™ 
type="javax.sql.DataSource™" 

name="jdbc/rest-security" 

username="root" password="root"™" 
url="jdbc:mysql://localhost:3306/simple service book" 
validationQuery="select 1 from users"/> 


然后 ,设置 DataSourceRealm 并 使 用 该 数据 源 。 


<Realm className="org.apache.catalina.realm.DataSourceRealm" 
dataSourceName="jdbc/rest-security" 

userTable="users" 

userNameCol="user name" 

userCredCol="user pass" 

userRoleTable="user roles" 

roleNameCol="role name"/> 


同 6.3.1 节 示例 类 似 ，Eclipse 内 置 的 Tomcat 配 置 如 图 6-13 所 示 。 


:7 辐 咬 量 :大 "Orv7Q@G7: 甫 Yr: 名 四 7 有 有期" 视 " 世 Or， 
Bpck Non yp| -OG | 


1.0" encoding="UTF-8"?> 
shutdown-~" SHUTDOWN "> 


MJ = = = 
[Ey > security-rest [axrrs2-guide master] SSLEngine="on" classMam="org.apache.catalina.core.AprlLifecyclelistener™” /> 


售 Servers 《Listener className="org.apache.cataslina.core.]asperListener”/> 
区 Tomcat v7.0 Server at localhost-ce 《Listener className="org.apache.catalina.core.JreNemoryLeakPreventionListener” /> 


贺 catalina.policy 
国 catalina.properties 


《Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecyclelListener™” /> 
《Listener className="org.apache.catalina.core.ThreadLocalleakPreventionlistener” /> 
GlobalNamingResources> 

四 contedxml <Resource auth="Container™” description="“User database that can be updated and saved” 
站 Server.xml factory-"org.spache.catalins.users.MemoryUserDatabaseFactory” name-"UserDatabsse" 
四 torncat-usersxml pathname-"conf/tomcat-users.xml” type-"org.apache.catalina.UserDatabase" /> 


国 webaml ~ - . 
<Resource auth="Container™” driverClassName="org.gjt.mm.mysql.Driver”™ 


type="javax.sql.DataSource” nane="jdbc/rest-security” usernane="root" 
password-"root” url-"jdbc:mysql://localhost:3366/simple secrvice book” 
validationQuery="select 1 from users” /> 


/GlobalNamingResources> 


<Service |name="Catalina”> 
<Connector connectionTimeout="20000”port="8989”protocol= "HTTP/1.1I” 
redirectPort="8443” /> 


onnector port="8969” protocol="AJP/1.3” redirectPort="8443" /> 
defaultHost="localhost" nane="Catalina”> 


<Realm className="org.apache.catalina.realm.DataSourceRealm" 
datasourceName="jdbc/rest-security" userTable="users”" userNameCol="user_name™" 
uscrCredCol="user pass” userRolcTable="user roles” roleNamcCol="role naome™” /> 


[HostohonBase="webapps” autoDeploy="true"” name="localhost"” unpackWARs="true"> 
docBase="security-rest” path="/security-rest" reloadable="true" 
source="org.eclipse.jst.j2ee.server:security-rest"” /> 
/Host> 
</Engine> 
/Service> 
</Server> 


图 6-13 ”在 Eclipse 中 为 Tomcat 插 件 配置 Realm 
(2) 数据 库 驱 动 
同 6.3.1 节 示例 ， 复 制 MySQL 的 JDBC 驱 动 到 yCATALINA_HOME/lib 目 录 。 
(3) 配置 应 用 


同 6.3.1 节 示例 ， 配 置 /security-rest/src/main/webapp/WEB-INF/web.xml 文 件 。 注 意 此 处 省 略 相同 部 分 。 


<resource-ref> 
<description>MySQL DB Connection Pool</description> 
<res-ref-name>jdbc/rest-security</res-ref-name> 
<res-type>javax.sql .DataSource</res-type> 
<res-auth>Container</res-auth> 
<res-sharing-scope>Shareable</res-sharing-scope> 
</resource-ref> 
<login-config> 
<auth-method>FORM</auth-method> 
<form-login-config> 
<form-login-page>/login.html</form-login-page> 
<form-error-page>/error.html</form-error-page> 
</form-login-config> 
</login-config> 
<welcome-file-list> 
<welcome-file>/index.html</welcome-file> 
</welcome-file-list> 


(4) 登录 页 面 


创建 并 编辑 登录 页 面 /security-rest/src/main/webapp/login.html。 


<form action="j] security check"> 
<div> 
<span>User Name</span> 
<input id="j username" name="j] username" type="text" /> 
</div> 
<div > 
<span>Pass Word</span> 
<input id="j password" name="j password" type="password" /> 
</div> 
<input type="submit" value="Sign In" /> 
</form> 


Firefox ™ 


b 3 EE localhost8080/security-resty 


User Name 


Pass Word 


6-14 登录 页 面 


如 图 6-14 所 示 ， 启 动 服务 后 ， 访 问 http://localhost:8080/security-rest/webapi/books， 页 面 将 跳 转 至 登录 页 面 。 
下 面 是 详细 的 测试 用 例 。 

(5) 认证 和 授权 测试 

测试 用 例 1 ( 见 表 6-7) ， 访 问 地 址 为 http://localhost:8080/security-rest/， 页 面 跳 转 至 登录 页 面 。 


表 6-7 摘要 认证 测试 用 例 1 


测试 要 素 说 明 
测试 地 址 http://localhost:8080/security-rest/ 

测试 方法 FORM jsecuritycheck 

测试 用 户 eric role=admin 

测试 结果 302 Found 


当 用 户 信息 提交 后 ， 服 务 器 处 理 登 录 信 息 返回 HTTP 状 态 码 302 (Found) ， 重 定向 请 求 ， 然 后 页 面 跳 转 到 首页 index.html， 返 回 200 OK， 如 图 6-15 所 示 。 


由 GETj_security_check2j_usernan localhost:8080 


因 GET /security-rest/ 200 OK localhost:8080 
由 GET jquery.js 200 OK localhost:8080 
四 GET restbook.js 200 OK localhost:8080 


图 6-15 ”摘要 认证 测试 用 例 1 结果 
测试 用 例 2 ( 见 表 6-8) ， 使 用 admin 角 色 登 录 后 ， 测 试 是 否 具有 访问 创建 新 图 书 的 资源 地 址 的 权限 。 结 果 返 回 HTTP 状 态 码 200 OK。 


表 6-8 摘要 认证 测试 用 例 2 


测试 要 素 说 明 
测试 地 址 http://localhost:8080/security-rest/webapi/books 
测试 方法 POST 

测试 用 户 eric role=admin 

测试 结果 200 OK 


测试 用 例 3 ( 见 表 6-9) 使 用 user 角 色 登 录 后 ， 测 试 是 否 具有 访问 创建 新 图 书 的 资源 地 址 的 权限 。 结 果 返 回 HTTP 状 态 码 403 Forbidden。 


表 6-9 ”摘要 认证 测试 用 例 3 


测试 要 素 说 明 
测试 地 址 http://localhost:8080/security-rest/webapi/books 
测试 方法 POST 

测试 用 户 caroline role=user 

测试 结果 403 Forbidden 


(6) 表单 认证 


如 图 6-16 所 示 ， 通 过 断 点 栈 可 以 观察 到 ，DataSourceRealm 类 的 authenticate() 方 法 被 表单 认证 类 FormAuthenticator 的 authenticate() 调 用 ， 匹 配 请 求 信息 和 数据 库 认 证 信息 。 


CEIRSCTTETTE 
流 虽 有 国 巡 | 勾 信 -过 | 了 | 鲜 了 Value 
pS Daemon Thread [http-bio-8080-exec-3] (Running) 从 this DataSourceRealm (id 
oD Daemon Thread [http-bio-8080-exec-4] (Suspended) dbConnection PoolingDataSource$Pp 
三 DataSourceRealm.authenticate(Connection, String, String) line: 345 username "eric" (id=60) 
ine: 292 credentials "han" (id=65) 
FormAuthenticator.authenticate(Request, HttpServiletResponse, Logi dbCredentials "han" (id=91) 
FormAuthenticator(AuthenticatorBase).invoke(Request, Response) hi validated true 
StandardHostValve.invoke(Request, Response) line: 171 list ArrayList<E> (id=92) 
ErrorReportValve.invoke(Request, Response) line: 99 
StandardEngineValve.invoke(Request, Response) line: 118 
CoyoteAdapter.service(Request, Response) line: 408 


username ) ) ; 
return (null); 


} 


ArrayList<String> list = getRoles(dbConnection, username),; 


// Create and return a suitable Principal for this user 
return (new GenericPrincipal(username, credentials, list)); 


图 6-16 ”DataSourceRealm 类 的 authenticate0 方 法 


6.3.4 ”表单 认证 与 JAASRealm 


JAAS (Java Authentication&Authorization Service，Java 认 证 和 授权 服务 ) 是 Java 平 台 认 证 和 授权 的 标准 规范 (JSR 196 标 准 ) ，JAAS 只 能 使 用 表单 认证 方式 获取 用 户 登录 信息 。Tomcat 提 供 了 基 
于 JAAS 的 JAASRealm， 本 示例 将 使 用 表单 认证 和 JAASRealm 展 示 一 个 JAAS 认 证 授权 的 实现 过 程 。 


(1) 创建 Realm 所 需 的 数据 表 
同 6.3.1 节 的 数据 库 脚 本 ， 使 用 “mysql-uroot-p<security.sql” 命 令 导 入 。 
(2) 配置 JAASRealm 


配置 $CATALINA_BASE/conf/server.xml， 添 加 JAASRealm 的 定义 。 


<Context docBase="security-rest" 

eR > 

<Realm className="org.apache.catalina.realm.JAASRealm" 
appName="RestJaasRealm" 
roleClassNames="com.example.jaas.RestRolePrincipal™ 
userClassNames="com.example.jaas.RestUserPrincipal"/> 

</Context> 


Realm 定 义 在 context 中 ， 否 则 会 导致 角色 POJO 字 段 roleClassNames 和 用 户 POJO 字 段 userClassNames 中 定义 的 类 找 不 到 。appName 定 义 的 名 字 和 JAAS 配 置 文件 restJaas.conf 中 定义 的 必须 一 致 。 
在 Eclipse 中 ， 其 内 置 的 Tomcat JAASRealm 配 置 如 图 6-17 所 示 。 


(3) JAAS 配 置 文件 


实现 JAAS 需 要 为 JAAS 框 架 提供 一 个 配置 文件 ， 本 例 使 用 /security-rest/src/main/resources/restJaas.conf。 


RestJaasRealm{ com.example.jaas.RestLoginModule required; }; 


二 


:加 同和 久 i#-O-Q%- OBOF- EDN Or 


ERall es 二 <?xXm] version="]1.0" encoding="UTF-8"?> 
二 Be 图 B <Server hort="8885” shutdoun="SHUTDOWN"> 
让 > security-rest [ax-r52-9ui Istener SSLEngine="on” className="org.apache.catalina,.core.AMprLifeq 
3 Servers <Listener className="org.apache.catalina.core.JasperListener"/> 
久 Tomcatv?,0 Server at lc 《Listener className="org.apache.catalina.core.JreMemoryLeakPreventio 
国 catalina.policy 《Listener className="org.apache, catalina.mbeans.GlobalResourcesLifecy 
国 catalina.properties <Listener className="org.apache.catalina.core.ThreadLocalLeakPrevent 
<GlobalNaminegResources> 
国 contextxml <Resource auth="Container” description="User database that can be 
[0 Serverxml </GlobalNamineResources> 


网 tomcat-users.xml 
国 web.xml 12€ [service home-"catalina> 


Sriiector connectionTimeout="28008" port="8080" protocol="HTTP/ 
ector port="8809" protocol="AJP/1.3" redirectPort="8443"/> 


onn 
<Engine defaultHost="localhost” name="Catalina"> 
<Host lappBase="webapps” autoDeploy="true” name="localhost" u 


<Context HocBase="security-rest" path="/security-rest” reload 


<Realm className="org.apache,.catalina.realm. JAASRealm" 
appName="Rest]aasRealm" 

roleClassNames=" com. example.jaas.RestRolePrincipal” 
userClassNames="cCom. example. jaas.RestUserPprincipal"/> 
</Context> 


</Host> 
</Engine> 
</Service> 
</Servery> 


图 6-17 在 Eclipse 中 为 Tomcat 插 件 配置 JAASRealm 


名 称 RestJaasRealm 与 图 6-17 中 的 appName 必 须 一 致 。 其 中 第 一 个 参数 是 登录 模块 的 类 全 名 ， 第 二 个 参数 的 取 值 见 表 6-10。 


表 6-10 JAAS 配 置 行 第 二 个 参数 取 值 和 说 明 


参数 值 说 明 
Required 该 模块 必须 认证 用 户 ， 如 果 认 证 失败 ， 那 么 使 用 其 他 登录 模块 认证 
Requisite 如 果 认 证 失败 ， 将 终止 认证 
Sufficient 如 果 认证 成 功 ， 即 获得 登录 认证 ; 如 果 认证 失败 ， 使 用 其 他 登录 模块 认证 
Optional 认证 将 继续 下 去 ， 即 使 该 模块 认证 成 功 

(4) JAAS 实 现 类 


JAAS 的 实现 类 目录 为 jax-rs2-guide\sample\6\security-rest\src\mainNavaNcomNexampleNaas， 其 中 定义 了 4 个 JAAS 实 现 类 ， 见 表 6-11。 


表 6-11 JAAS 实 现 类 列表 


实现 类 作用 实现 类 文件 名 
LoginModule 实现 类 RestLoginModule.java 
LoginModule 实现 类 的 数据 库 操作 类 RestLoginDao.java 
Role 接口 POJO 类 RestRolePrincipal.java 
User 接口 POJO 类 RestUserPrincipal.java 


(5) 配置 [VM 启动 参数 


前 面 设置 的 JAAS 配 置 文 件 需要 加 入 启动 参数 中 ， 以 便 JAAS 框 架 识别 。 


-Djava.security.auth.1login.config="D:\taries\github\jax-rs2-guide\sample\6\security-rest\src\main\resources\restJaas.conf™" 


Eclipse 内 置 Tomcat 虚 拟 机 参数 设置 如 图 6-18 所 示 。 


四 serverxml | 国 restlaasconf Edit launch configuration properties 


OQverview 


| General Infor mation Name; Tomcatv10 Server atlocalhost 


Specify the host name and cther com ( 目 Server [gs ArgumentsY $0 Clayspath| 外 Source| 国 Ervironment| 图 Common 


Server narmei Tomcaty Program argurmentsl 


Host name: localhost | statt 
Runtime Environrment: 
Configuration Path; 


ET 


| Server Locations 


Specify the Server path ti,e, catalina, ba VM argument3i 


published with no modules present to| 
Deatalina, base=m"Di\ aries\tomeat working" -Deatalina, home="DN aquarius\apache-tomecat-7,0,42" 
Use workspace metadata (does nd Dwtp.deploy="D'\ +aries\tomcat workingWwwtpwebapps" -Djava,endorsed. dirs="D'\ +aquarius\apache- 
© Use Tomcat installation (takes co tormcat-T,0,42vzendorsed 加 日 auth,login,config="D'N\ +aries\github' s2-quide\sarmple 
‘Bsecurty-rest\src\main\resou ‘restlaas,conf" 


©®@ Use custom location (does not m 


Server path' DiN\r+arles\omcat ' 


Set deploy path to the default value 


图 6-18 ”在 Eclipse 中 为 Tomcat 插 件 配置 支持 JAAS 的 启动 参数 
(6) JAAS 流 程 
在 JAASRealm.authenticate 认 证 方法 中 ， 有 以 下 两 个 主要 对 象 。 
“ CallbackHandler: 持 有 登录 信息 的 回调 。 
“ LoginContext: 通过 配置 文件 感知 LoginModule 实 现 类 的 上 下 文 。 
认证 分 为 两 个 步骤 : 


第 一 步 ， 验 证 登录 信息 合法 性 对 应 RestLoginModule 类 的 login() 方 法 ， 如 图 6-19 所 示 。 


4 [只 Daemon Thread [http-bio-8080-exec-8] (Suspended (breakpoint at line 48 in RestLoginModule)) 
RestLoginModule.login( line 48 | 

NatrveMethodAccessormpl.invoke0(Method, Object Object[]) line: not available [native method] 

NativeMethodAccessorImpl.invoke(Object, Object[]) line: 57 

DelegatingMethodAccessorImpl.invoke(Object, Object[]) line: 43 

Method,invoke(Object, Object…] line: 606 

LoginContext.invoke(String) line: 784 

LoginContext.access$000(LoginContext, String) line: 203 

LoginContext$4.run( line: 698 

LoginContext$4,.run( line: 696 

AccessController,doPrivileged(PrivilegedExceptionAction<T>) line: not available [native method)] 

LoginContext,invokePriv(String) line: 695 

LoginContext.login(Q line: 594 

JAASRealm.authenticate(String, CallbackHandler) line: 435 

JAASRealm.authenticate(String, String) line: 356 

FormAuthenticator.authenticate(Request, HttpServletResponse, LoginConfig) line: 296 

FormAuthenticator(AuthenticatorBase),invoke(Request, Response) line: 450 

StandardHostValve.invoke(Request, Response) line: 171 


图 6-19 ”调用 RestLoginModule 类 的 login0 方 法 的 栈 


第 二 步 ， 获 取 登 录 身 份 信息 对 应 RestLoginModule 类 的 commit() 方 法 ， 如 图 6-20 所 示 。 


4 只 Daemon Thread [http-bio-8080-exec-8] (Suspended (breakpoint at line 79 in RestLoginModule)) 
RestLoginModule.commit0 line: 79 

NativeMethodAccessorlmpl,invoke0(Method， Object Object[]) line not available [natrve method] 
NativeMethodAccessorImpl.invoke(Object, Object[]) line: 57 
DelegatingMethodAccessorImpl,invoke(Object, Object[]) line: 43 

Method.invoke(Object, Object...) line: 606 

LoginContext.invoke(String) line 784 

LoginContext.access$000(LoginContext, String) line 203 

LoginContext$4.run() line 698 

LoginContext$4.run( line 696 

AccessController.doPrivileged(PrivilegedExceptionAction<T>) line: not available [natrve method] 
LoginContext,invokePriv(String) line: 695 

LoginContext.loginQ line: 595 

JAASRealm.authenticate(String, CallbackHandler) line: 435 

JAASRealm.authenticate(String, String) line: 356 

FormAuthenticator,authenticate(Request, HttpServletResponse, LoginConfig) line: 296 
FormAuthenticator(AuthenticatorBase).invoke(Request, Response) line: 450 
StandardHostValve.invoke(Request, Response) line: 171 


图 6-20 ”调用 RestLoginModule 类 的 commit0 方 法 的 栈 


到 此 ，JAAS 在 REST 式 的 Web 服 务 中 的 应 用 就 讲述 完毕 了 ， 希 望 读 者 对 此 有 清楚 的 认识 。 还 要 说 明 的 是 ，JAAS 这 种 验证 实现 有 些 重型 ， 对 于 轻 量 级 的 REST 应 用 以 及 多 模块 分 布 式 的 Web 服 务 而 
，JAAS 验 证 的 实现 并 不 令 人 满意 。 


中 


6.3.5 “证书 认 证 与 UserDatabaseRealm 


6.1 节 介绍 了 证 书 认 证 的 技术 背景 ， 证 书 认 证 包括 对 客户 端 (有 时 是 对 服务 器 ) 的 单项 认证 和 双向 认证 。 本 节 结 合 Tomcat 提 供 的 UserDatabaseRealm， 采 用 双向 认证 来 演示 证 书 认证 的 实现 。 


(1) 双向 认证 


双向 认证 一 词 对 应 的 英文 是 Mutual Authentication 或 者 Two way Authentication， 是 指 服务 器 和 客户 端 在 通信 之 前 ， 需 要 通过 对 方 提供 证 书 进行 相互 认证 其 身份 ， 此 后 双方 使 用 协商 好 的 加 密 算法 加 
密 数 据 通信 。 这 个 身份 认证 过 程 就 是 TLS 通 信 “握手 。 (TLS Handshake) 的 过 程 。 其 过 程 如 图 6-21 所 示 。 


如 图 6-21 所 示 ，TLS 双 向 认证 这 一 过 程 简单 的 描述 就 是 : 客户 端 向 服务 器 发 起 Hello 请 求 会 话 ， 服 务 器 接收 请 求 后 应 答 Hello， 然 后 双方 交换 证 书 的 公 钥 和 加 密 算法 ， 确 认 对 方 身份 并 协商 将 要 使 用 的 加 密 
算法 。 握 手 过 程 结束 后 ， 双 方 使 用 达成 一 致 的 加 密 算法 加 密 数 据 通 信 。 接 下 来 ， 讲 述 握手 过 程 中 使 用 的 证 书 是 如 何 生成 并 被 签发 和 授权 信任 的 。 


(2) 证 书 管理 


在 Java 平 台 ,证 书 ( 密 钥 信 息 ) 存储 在 keystore 文 件 中 。 


通常 的 流程 是 系统 首先 在 keystore 中 生成 自 签 证 书 ， 然 后 将 其 导出 为 自 签 证 书 文件 ， 接 着 向 CA 机 构 提交 CSR (Certificate Signing Request， 证 书签 发 请 求 ) 。 CA 接收 请 求 后 ， 使 用 私 钥 签发 该 证 书 ， 
并 将 CA 签发 的 证 书 和 CA 证 书 (包含 CA 公 钥 ) 返回 。 系 统 将 CA 证 书 导 入 keystore， 即 信任 CA， 此 后 TLS 通 信 过 程 中 ， 凡 是 该 CA 签发 的 证 书 ， 该 系统 皆 信任 ， 如 图 6-22 所 示 。CA 签 发 的 证 书 在 该 系统 与 外 系 
统 通信 时 ， 作 为 该 系统 身份 认证 证 书 提交 。 


简化 的 流程 是 省 略 CA 签 发 证 书 这 个 流程 ， 双 方 的 自 签证 书 可 以 作为 通信 时 身份 认证 的 证 书 ， 即 在 通信 前 ， 外 系统 已 经 导入 该 系统 的 自 签证 书 ， 对 其 信任 。 


SSLITLS 
Mutual Authentication 
Handshaking 


| 


| 
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| 
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| 
一 certificate 一 一 
| 
| 
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| 
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| 
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| 
| 
| 
—————— (terifcate—————~ 
| 
| 
一 Cient Key Exchange 一 一 一 人 
| 
一 一 一 certficate Verify 
| 
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| 

| 
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| 
| 
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图 6-21 TLS 双 向 认证 握手 流程 


self-Signed.cer” 


PrivateKeyEntry 
Self 


trustedCertEntry 
CA 
(Other) 


图 6-22 证 书签 发 流程 


(3) 密 钥 和 证 书 管理 工具 


JDK 提 供 了 密 铀 和 证 书 管理 工具 keytool， 该 工 


实现 的 功能 和 JCE 规 范 提供 的 API 类 似 。 通 过 “keytool help” 命 令 可 以 得 到 表 6-12 所 示 的 参数 信息 。 


表 6-12 keytool 工 具 参 数列 表 


参数 功能 
-certreq 生成 证 书 请 求 
-changealias 更 改 条 目的 别名 
-delete 删除 条 目 
-exportcert 导出 证 书 
-genkeypair 生成 密 钥 对 
-genseckey 生成 密 钥 


-gencert 根据 证 书 请 求生 成 证 书 


参数 
-importcert 
-Importkeystore 
-keypasswd 
-list 
-printcert 
-printcertreq 
-printcrl 


-storepasswd 


功能 
导入 证 书 或 证 书 链 
从 其 他 密 钥 库 导 入 一 个 或 所 有 条 目 
更 改 条 目的 密 钥 密码 
列 出 密 钥 库 中 的 条 目 
打印 证 书 内 容 
打印 证 书 请 求 的 内 容 
打印 CRL 文件 的 内 容 
更 改 密 钥 库 的 存储 密码 


通过 keytool， 我 们 可 以 完成 下 列 证 书 管理 流程 。 


1) 服务 器 端 创建 自 签 证 书 ， 命 令 示例 如 下 。 


( 续 ) 


keytool -genkey -dname "CN=mars64,OU=Rest,O=JaxRs2,1=HaiDian,ST=Beijing,C=China" -alias 


server -keyalg RSA -keystore 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer.keystore -keypass 


restful -storepass restful -validity 60 


服务 器 的 别名 为 server， 签 发 证 书 的 算法 为 RSA， 有 效 期 为 60 天 。-dname， 即 唯一 判别 名 中 ，CN 使 用 测试 主机 的 hostname， 其 他 选项 没有 要 求 。 


2) 服务 器 端 导出 自 签证 书 ， 命 令 示例 如 下 。 


keytool -export -alias server -keystore 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer.keystore 


-storepass restful -rfc -file 


D:\-aries\github\jax-rs2-guide\sample\é6\security-rest\certificate\restServer.cer 


3) 客户 端 创建 自 签证 书 ， 命 令 示例 如 下 。 


keytool -genkey -dname "CN=mars64, OU=Rest, O=JaxRs2, L=HaiDian, ST=Beijing, 
C=China" -alias admin -keyalg RSA -keystore 
D:\-aries\github\jax-rs2-guide\sample\é6\security-rest\keystore\restAdminClient. 
keystore -keypass restful -storepass restful -validity 60 

keytool -genkey -dname "CN=mars64, OU=Rest, O=JaxRs2, IL=HuangGu, ST=Shenyang, 
C=China" -alias user -keyalg RSA -keystore 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restUserClient. 
keystore -keypass restful -storepass restful -validity 60 


由 于 我 们 要 演示 管理 员 和 普通 用 户 两 种 角色 ， 


4) 客户 端 导入 服务 器 证 书 ， 命 令 示 例如 下 。 


因此 ， 客 户 端 生成 了 两 个 证 书 并 分 别 保存 在 独立 的 keystore 文 件 中 ， 以 便 客户 端 程序 分 别 加 载 。 


keytool -importcert -noprompt -trustcacerts -alias server -file 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restServer.cer -keystore 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restAdminClient. 

keystore -storepass restful -keypass restful 

keytool -importcert -noprompt -trustcacerts -alias server -file 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restServer.cer -keystore 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restUserClient. 

keystore -storepass restful -keypass restful 


将 服务 器 导出 的 证 书 分 别 导入 客户 端的 两 个 keystore 中 。 


-list 查 看 导入 后 keystore 的 信息 ， 可 以 看 到 该 keystore 中 存储 的 私 钥 和 信任 的 公 钥 列 表 ， 以 别名 来 区 分 ， 命 令 示例 如 下 。 


keytool -list -keystore 


D:\-~aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restUserClient. 


keystore -storepass restful 


5) 客户 端 导出 自 签证 书 ， 命 令 示例 如 下 。 


keytool -export -alias admin -keystore 


D:\-aries\github\jax-rs2-guide\sample\é6\security-rest\keystore\restAdminClient. 


keystore -storepass restful -rfc -file 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restAdminClient .cer 


keytool -export -alias user -keystore 


D:\-~aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restUserClient. 


keystore -storepass restful -rfc -file 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restUserClient .cer 


6) 服务 器 端 导 入 客户 端 证 书 ， 命 令 示例 如 下 。 


keytool -importcert -noprompt -trustcacerts -alias admin -file 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restAdminClient .cer 


-keystore 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer. 
keystore -storepass restful -keypass restful 

keytool -importcert -noprompt -trustcacerts -alias user -file 
D:\-aries\github\jax-rs2-guide\sample\6\security-rest\certificate\restUserClient. 


Cer -keystore 


D:\-aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer. 
keystore -storepass restful -keypass restful 


7) 服务 器 端 权 限 配置 ， 命 令 示例 如 下 。 


<user username="CN=mars64, OU=Rest, O=JaxRs2, L=HaiDian, ST=Beijing, C=China™" 


password="null" roles="admin"/> 
<user username="CN=mars64, OU=Rest, O=JaxRs2, L=HuangGu, ST=Shenyang, C=China" 
password="null" roles="user"/> 


证 书 管理 完毕 后 ， 待 服务 器 和 客户 端 启动 加 载 。 接 下 来 ， 需 要 对 服务 器 端的 权限 进行 配置 。 根 据 上 述 客 户 端 的 两 个 角色 的 唯一 判别 名 ， 将 它们 的 角色 分 别 定义 为 admin 和 user。 
(4) 配置 服务 器 SSL 


Tomcat 服 务 器 支持 两 种 证 书 服 务 ， 一 种 是 APR (Apache Portable Runtime) ， 另 一 种 是 JSSE。 本 例 使 用 JSSE 方 式 。 


<Connector clientAuth="true" port="8443" minSpareThreads="5" 

maxSpareThreads="75" enableLookups="true" disableUploadTimeout="true" 
acceptCount="100" maxThreads="200" scheme="https" secure="true" 

SsLEnabled="true" 

keystoreFile= 
"D:\-~aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer.keystore" 
keystoreType="JKS" keystorePass="restful" 

truststoreFile= 
"D:\-~aries\github\jax-rs2-guide\sample\6\security-rest\keystore\restServer.keystore" 
truststoreType="JKS" truststorePass="restful" SSLVerifyClient="require" 
SSLEngine="on" sslProtocol="TLS" /> 


(5) 配置 应 用 


本 例 的 web.xml 配 置 参 考 6.3.3 节 的 示例 ， 唯 一 不 同 之 处 是 登录 配置 ， 如 下 所 示 。 


<login-config> 
<auth-method>CLIENT-CERT</auth-method> 
</login-config> 


(6) 认证 和 授权 测试 


浏览 器 动态 加 载 证 书 提交 请 求 并 不 常见 ， 本 示例 的 测试 参见 下 文 的 客户 端 实现 。 


通过 上 述 内 容 ， 相 信 读 者 对 在 REST 中 实现 认证 和 授权 有 了 深入 的 了 解 ， 并 结合 自己 的 项 目 有 了 初步 的 选择 。 第 11 章 的 综合 示例 会 给 出 一 种 客户 端 “ 记 忆 ” 当 前 用 户 信息 的 方案 ， 目 的 是 解决 REST 服 务 
分 模块 部 署 的 场景 问题 。 因 为 在 该 场景 下 ， 某 个 模块 “记忆 ”的 用 户 信息 无 法 与 其 他 模块 分 享 。 该 方案 并 没有 使 用 Cookie， 具 体 是 如 何 实现 的 ， 参 见 第 11 章 。 


6.4 JAX-RS 2.0 实 现 


6.3 节 通过 几 个 示例 展示 了 单独 使 用 容器 进行 认证 和 授权 的 过 程 。 本 节 将 展示 结合 上 述 的 容器 认证 ， 通 过 编码 进行 授权 的 流程 。 


1.Application 类 


Application 类 是 容器 中 REST 应 用 的 入 口 ， 安 全 相关 的 配置 要 在 这 里 完成 注册 ， 示 例 代码 如 下 。 


@ApplicationPath ("/webapi/*") 
public class AirResourceConfig extends ResourceConfig { 
public AirResourceConfig() { 
super (RolesAllowedDynamicFeature.class, BookResource.class); 


E 


在 这 段 代 码 中 ，Application 类 AirResourceConfig 注 册 了 RolesAllowedDynamicFeature 以 支持 6.2 节 讲述 的 JSR 250 注 解 ， 还 注册 了 资源 类 BookResource 以 实现 REST 服 务 。 


2. 资 源 类 


本 例 中 ， 与 其 他 章节 相 比 ， 与 授权 相关 的 资源 类 BookResource 的 实现 加 入 了 JSR 250 的 注解 和 JAX-RS 2.0 的 SecurityContext 接 口 ， 示 例 代码 如 下 。 


Q@Path ("books") 
public class BookResource { 
@RolesAllowed (value={"admin"})// 
关注 点 1 
: 根据 角色 授权 访问 
QGET 
Q@Produces ({ MediaType.APPLICATION JSON, MediaType.APPLICATION XML }) 
public Books getBooks (@Context final SecurityContext sc) { 
logMe (sc);// 
关注 点 2 
: 在 方法 中 获取 安全 上 下 文 
final Books books = bookService.getBooks(); 
BookResource .LOGGER. debug (books); 
return books; 
} 
private void logMe (final SecurityContext sc) { 
try { 
BookResource.LOGGER.info ("User=" + sc.getUserPrincipal () .getName ()); 
BookResource.LOGGER.info("User Role?=" + sc.isUserInRole ("user")); 
BookResource.LOGGER.info ("Auth way=" + sc.getAuthenticationSscheme()); 
} catch (final Exception e) { 
LOGGER.debug ("Cannot print credential info."+te); 
} 
} 
User=eric 
User Role?=false 
Auth way=BASIC 


在 这 段 代 码 中 ，GET 方 法 getBooks() 使 用 了 @RolesAllowed (value={“admin”}) 注解 ， 授 权 访问 此 方法 的 角色 为 admin， 见 关注 点 1。 此 时 ， 虽 然 容 器 的 配置 中 定义 了 user 角 色 可 以 访问 这 个 GET 方 
法 ， 但 是 应 用 级 别 的 权限 优先 级 高 于 容器 级 别 ， 在 此 定义 的 具有 更 细 粒 度 的 权限 约束 致使 user 角 色 不 能 访问 getBooks() 方 法 。getBooks() 方 法 定义 了 SecurityContext 实 例 作为 参数 ，SecurityContext 实 例 
携带 了 用 户 角色 的 相关 信息 ， 运 行 时 可 以 从 中 获取 当前 getBooks() 方 法 访问 者 的 角色 信息 ， 见 关注 点 2。 


3 .资源 测试 类 


Jersey 2.x 提 供 了 基本 认证 连接 过 滤器 (HttpBasicAuthFilter) 、 摘 要 认证 连接 过 滤器 (HttpDigestAuthFilter) ， 而 证 书 认 证 是 通过 设置 JerseyClient 内 部 的 SSLContext 字 段 实 现 的 。Jersey 2.5 开 始 
将 HttpBasicAuthFilter 和 HttpDigestAuthFilter 标 记 为 deprecated， 使 用 HttpAuthenticationFeature 统 一 配置 认证 。 


(1) 基本 认证 测试 


对 于 基本 认证 的 客户 端 测试 ， 分 别 测 试 普 通 连接 和 注册 HttpBasicAuthFilter 或 者 HttpAuthenticationFeature 的 连接 。 没 有 提供 基本 认证 的 连接 会 得 到 服务 器 返回 的 HTTP 状 态 码 401， 表 示 没有 通过 认 
证 的 错误 ， 对 应 的 预计 异常 类 是 NotAuthorizedException。 在 ClientConfig 实 例 中 注册 HttpBasicAuthFilter 实 例 的 连接 会 通过 认证 并 取得 访问 GET 方 法 的 权限 ， 从 服务 器 获得 Books 类 型 的 数据 。 示 例 代码 
如 下 。 


@Test (expected = javax.ws.rs.NotAuthorizedException.class) 
public void testGetAll() { 
final ClientConfig cc = new ClientConfig(); 
final Client client = ClientBuilder.newClient (cc); 
final Invocation.Builder invocationBuilder = client.target (BASE URI) .request (); 
invocationBuilder.get (Books.class); 
} 
Q@Test 
public void testGetAll2() { 
final ClientConfig cc = new ClientConfig(); 
//Jersey2.5-: cc.register (new HttpBasicAuthFilter ("caroline", "zhang")); 
HttpAuthenticationFeature feature = 
HttpAuthenticationFeature.basicBuilder () .nonPreemptive () 
.Credentials ("caroline", “zhang") .build(); 
cc.register (feature); 
final Client client = ClientBuilder.newClient (cc); 
final Invocation.Builder invocationBuilder = client.target (BASE URI) .request (); 
invocationBuilder.get (Books.class); 


(2) 摘要 认证 测试 
摘要 认证 的 客户 端 测试 和 基本 认证 测试 过 程 类 似 。 


对 于 基本 认证 的 客户 端 测 试 ， 分 别 测试 普通 连接 和 注册 HttpDigestAuthFilter 或 者 HttpAuthenticationFeature 的 连接 。 没 有 提供 摘要 认证 的 连接 会 得 到 服务 器 返回 的 HTTP 状 态 码 401， 表 示 没 有 通过 
认证 的 错误 ， 对 应 的 预计 异常 类 是 NotAuthorizedException。 在 ClientConfig 实 例 中 注册 HttpDigestAuthFilter 实 例 的 连接 会 通过 认证 并 取得 访问 GET 方 法 的 权限 ， 从 服务 器 获得 Books 类 型 的 数据 。 示 例 
代码 如 下 。 


QTest 
Public void testGetaAl112 () { 
final ClientConfig cc = new ClientConfig(); 
//2.5-: cc.register (new HttpDigestAuthFilter ("caroline"，"zhang") ) 7 
HttpAuthenticationFeature feature = 
HttpAuthenticationFeature.digest ("caroline", "zhang"); 
cc.register (feature); 
final Client client = ClientBuilder.newClient (cc); 
final Invocation.Builder invocationBuilder = client.target (BASE URI) .request (); 
invocationBuilder.get (Books.class); 加 


} 


(3) 证 书 认证 测试 


对 于 证 书 认证 的 客户 端 测 试 ， 需 要 用 到 6.3.5 节 关于 证 书 认 证 的 知识 。 首 先 设置 keystore 到 SslConfigurator 类 的 实例 中 ，SslConfigurator 实 例 通 过 本 地 证 书信 息 生 成 javax.net.ssl.SSLContext 类 的 实 
例 ， 接 着 SSLContext 实 例 赋值 于 REST 客 户 端 ， 作 为 SSL 上 下 文字 段 ， 此 时 REST 客 户 端 向 服务 器 发 起 握手 流程 ， 即 可 实现 上 文 所 述 的 双向 认证 。 授 权 逻 辑 可 参考 本 章 前 言 内 容 。 示 例 代 码 如 下 。 


private Client buildSecureClient (boolean admin) { 
String keystore; 


if (aqmin) { 

keystore = "restAdminClient.keystore"; 
} else { 

keystore = "restUserClient.keystore"; 


} 
final SslConfigurator sslConfig = SslConfigurator.newInstance() .trustStoreFile (keystore) 
.trustStorePassword ("restful") .keyStorerFile (keystore) .keyPassword ("restful"); 
final SSLContext sslContext = sslConfig.createSsLContext (); 
final Client client = ClientBuilder.newBuilder() .sslContext (sslContext) .build(); 
return client; 
i 
@Test 
public void testGetAll() { 
final Client client = buildSecureClient (false); 
final Invocation.Builder invocationBuilder = client.target (BASE URI) .request (); 
invocationBuilder.get (Books.class); 
} 
@Test (expected = javax.ws.rs.ForbiddenException.class) 
public void testPost() { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
buildSecureClient (false) .target (BASE URI) 
.request (MediaType.APPLICATION JSON TYPE) .post (bookEntity, Book.class); 
} 


6.5 ”其 他 安全 考虑 


在 完成 了 通用 的 认证 和 授权 的 实现 后 ， 我 们 的 REST 服 务 还 要 考虑 很 多 安全 方面 的 问题 。 完 整 的 安全 策略 推荐 阅读 专业 领域 的 书籍 ， 在 此 简单 介绍 一 下 AJAX 的 跨 域 安全 和 OAuth。 


(1) AJAX 跨 域 安全 


和 其 他 Java EE 标准 一 样 ，JAX-RS 2.0 并 没有 给 出 对 XSS (Cross Site Script， 跨 站 脚本 攻击 ) 和 CSRF (Cross-Site Request Forgery， 跨 站 点 请 求 伪造 ) 等 攻击 手段 的 防范 标准 。 因 此 ， 一 方面 需要 开 
发 者 在 编码 中 防止 出 现代 码 级 别 的 漏洞 ， 另 一 方面 需要 开发 者 实现 规避 攻击 风险 的 代码 。 举 例 来 说 ， 可 以 借助 JAX-RS 2.0 定 义 Providers 接 口 来 实现 过 滤器 ，Jersey 2.x 提 供 了 CSRF 防 御 的 过 滤器 实现 类 
CsrfProtectionFilter 可 供 参 考 。 对 于 第 4 章 示例 代码 包 中 提供 的 关于 CORS (Cross-Origin Resource Sharing， 跨 域 资源 共享 ) 的 实例 是 基于 “HTTP 头 不 会 被 脚本 算 改 ”这 一 理论 的 ， 在 联合 部 署 不 同 应 用 
的 REST 服 务 的 场景 中 ，CORS 是 必要 的 解决 方案 。 


(2) OAuth 和 OAuth2 


np 


虽然 OAuth 和 OAuth2 是 当今 Web 服 务 (尤其 是 社交 网 络 ) 的 流行 的 认证 协议 ， 但 是 JAX-RS 2.0 并 没有 给 出 相关 定义 。Jersey 2.x 对 这 两 种 协议 的 实现 处 于 开发 状态 ， 在 本 书 发 稿 时 ，Jersey 2.x 提 供 了 
OAuth 和 OAuth2 规 范 的 客户 端 实现 和 OAuth 协 议 的 服务 器 端 支持 包 ， 尚 未 提供 OAuth2 的 服务 器 端 支持 包 。 读 者 可 以 参考 Jersey 源 代码 中 security 目 录 的 进展 情况 。Jersey 2.x 的 OAuth2 客 户 端 支持 包 
oauth2-client 的 依赖 定义 示例 如 下 。 


<dependency> 
<groupId>org.glassfish.jersey.security</groupId> 
<artifactId>oauth2-client</artifactId> 
<version>$ {project .version}</version> 
</dependency> 


6.6 本章 小 结 


本 章 全 面 讲 述 了 与 REST 安 全 相关 的 理论 和 实践 。 其 中 6.1 节 介绍 了 HTTP 基 本 认证 、HTTP 摘 要 认证 、 表 单 认证 和 证 书 认证 ;6.2 节 介绍 了 容器 和 应 用 两 种 权限 管理 方式 ;6.3 节 结合 Tomcat 的 Realm 机 
制 ， 分 别 演示 了 4 种 认证 的 实践 ，6.4 节 演示 了 使 用 JAX-RS 2.0 定 义 的 安全 注解 ， 通 过 编码 实现 权限 管理 ，6.5 节 简 述 了 其 他 安全 技术 。 下 一 章 ， 我 们 开始 讲述 REST 的 测试 。 


第 7 章 ” REST 测试 


本 章 讲述 如 何 使 用 Jersey 提 供 的 测试 框架 实现 对 基于 JAX-RS 2.0 的 Web 服 务 进行 自动 化 测试 。 


自动 化 测试 是 软件 质量 保证 的 必要 手段 ， 是 减少 开发 团队 重复 劳动 的 利器 ， 同 时 也 是 敏捷 开发 的 重要 环节 。 项 目 源 代 码 的 代码 覆盖 率 即 指 测试 代码 中 对 源 代码 的 公有 方法 的 覆盖 情况 ， 是 
Cl (Continuous Integration， 持 续集 成 ) 和 CD (Continuous Delivery， 持 续 交 付 ) 中 的 重要 指标 之 一 。 


使 用 JUnit 结 合 Jersey 的 测试 框架 ， 能 够 轻松 地 实现 单元 测试 、CI 测 试 和 系统 测试 。Jersey 提 供 了 4 种 内 置 容 器 ， 测 试 过 程 对 外 置 容器 没有 天 然 的 依赖 。 


全 阅读 指导 “第 7 章 没有 单独 的 示例 项 目 ， 因 为 测试 存在 于 各 个 项 目 中 ， 可 参考 2.5 节 的 示例 项 目 : 


jax-rs2-guide\sample\2\5simple-service-webapp-spring-jpa-jquery 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/2/5simple-service-webapp-spring-jpa-jquery。 


7.1 ”Jersey 测 试 框架 


Jersey 核 心 测试 框架 包 jersey-test-framework-core 提 供 了 测试 环境 中 容器 和 客户 端 实 例 ， 使 开发 者 不 必 编 写 管理 容器 和 客户 端的 样板 代码 。 


在 没有 Jersey 核 心 测试 框架 支持 的 测试 类 中 ， 开 发 者 需要 在 编写 测试 用 例 的 同时 ， 维 护 测试 容器 和 客户 端 代码 。setUp0 方 法 中 的 代码 都 是 样板 代码 ， 这 些 样板 代码 会 在 使 用 Jersey 核 心 测试 框架 的 测试 
类 中 消失 。 没 有 使 用 Jersey 测 试 框架 的 测试 ， 示 例 代码 如 下 。 


public class TIMyResourceTest { 
public static final String BASE URI = "http://localhost:8080/webapi/™"; 
Private HttpServer server; 
private WebTarget target; 
QBefore 
public void setUp() throws Exception { 
final ResourceConfigrc = new ResourceConfig() .packages ("com.example"); 
final URI uri = URI.create (BASE URI); 
server = GrizzlyHttpServerFactory.createHttpServer (uri, rc); 
server.start (); 
final ClientConfig cc = new ClientConfig(); 
final Client client = ClientBuilder.newClient (cc); 
target = client.target (BASE URI) .path ("books"); 


} 

QAfter 

public void tearDown() throws Exception { 
if (server != null) { 


server.stop(); 
} 
} 
@Test 
public void testQueryGetXML() { 
final WebTarget queryTarget = target.path("/book") 
.queryParam("id", Integer.valueOf (1)); 
final Invocation.Builder invocationBuilder = 
queryTarget .request (MediaType .APPLICATION XML TYPE); 
final Response response = invocationBuilder.get (); 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 


使 用 了 Jersey 核 心 测试 框架 后 ， 代 码 量 减少 了 很 多 ， 示 例 代 码 如 下 。 


public class TIMyResourceJTFTest extends JerseyTest { 

private static final String BASEURI = "books/"; 

QOverride 

protected Application configure() { 
return new ResourceConfig (BookResource.class); 

: 

@Test 

public void testQueryGetXML() { 
final WebTarget queryTarget = target (BASEURI + "book") 
.queryParam("id", Integer.valueOf (1)); 
final Invocation.Builder invocationBuilder = 
queryTarget .request (MediaType.APPLICATION XML TYPE); 
final Response response = invocationBuilder.get(); 

http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 

} 


在 这 段 代码 中 ，TIMyResourceJTFTest 类 继承 了 Jersey 核 心 测试 框架 类 JerseyTest， 其 测试 代码 中 只 有 覆盖 configure() 方 法 是 与 测试 用 例 无 关 的 代码 。 在 测试 用 例 中 可 以 直接 使 用 target0 方 法 从 测试 框 
架 中 获取 WebTarget 类 的 实例 ， 余 下 的 代码 都 是 测试 用 例 本 身 的 内 容 。 


在 项 目 中 使 用 Jersey 核 心 测试 框架 包 时 ， 需 要 在 pom.xml 文 件 中 定义 依赖 。Jersey 核 心 测试 框架 提供 了 4 种 内 置 容器 ， 默 认 使 用 Grizzly 2 容器 。 因 此 ， 定 义 Jersey 核 心 测试 框架 依赖 的 同时 ， 需 要 定义 测 
试 框架 Grizzly 2 容器 包 jersey-test-framework-provider-grizzly2。 和 否则 ， 运 行 时 会 报 TestContainerException 异 常 。 


Jersey 测 试 框架 核心 的 依赖 定义 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.test-framework</groupId> 
<artifactId>jersey-test-framework-core</artifactId> 
<version>$ {jersey.version}</version> 

</dependency> 


下 面 是 4 种 内 置 容器 的 定义 。 


1) Jersey 内 置 容器 Grizzly 2 依赖 定义 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.test-framework.providers</groupId> 
<artifactId>jersey-test-framework-provider-grizzly2</artifactId> 
<version>$ {jersey.version}</version> 

</dependency> 


测试 框架 Grizzly 2 容器 所 在 的 模块 为 jersey-test-framework-provider-grizzly2。Grizzly 轻 量 级 HTTP 容 器 是 Jersey 测 试 框架 的 默认 容器 。 


2) Jersey 内 置 容器 inmemory 依 赖 定义 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.test-framework.providers</groupId> 
<artifactId>jersey-test-framework-provider-inmemory</artifactId> 
<version>$ {jersey.version}</version> 

</dependency> 


测试 框架 内 存 容 器 所 在 的 模块 为 jersey-test-framework-provider-inmemory， 内 存 容器 不 是 一 个 真正 的 容器 。 测 试 框架 直接 调用 应 用 的 AP1， 因 此 没有 真正 的 网 络 通信 。 内 存 容 器 不 支持 真正 的 容器 
特性 和 Servlet， 但 是 非常 适合 作为 单元 测试 阶段 的 容器 。 


3) Jersey 内 置 容器 JDK-HTTP 依 赖 定义 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.test-framework.providers</groupId> 
<artifactId>jersey-test-framework-provider-jdk-http</artifactId> 
<version>$ {jersey.version}</version> 

</dependency> 


测试 框架 JDK 版 HTTP 容 器 所 在 的 模块 为 jersey-test-framework-provider-jdk-http，JDK 版 HTTP 容 器 是 JDK。 


4) Jersey 内 置 容器 simple-HTTP 依 赖 定义 如 下 : 


<dependency> 
<groupId>org.glassfish.jersey.test-framework.providers</groupId> 
<artifactId>jersey-test-framework-provider-simple</artifactId> 
<version>$ {jersey.version}</version> 

</dependency> 


测试 框架 简单 版 HTTP 容 器 所 在 的 模块 为 jersey-test-framework-provider-simple， 集 成 Jersey 的 轻 量 级 HTTP 容 器 。 


在 测试 类 中 使 用 4 种 内 置 容器 非常 方 人 


org.glassfish.jersey.test.simple.SimpleTestContainerFactory。 


， 只 需要 在 覆盖 configure() 方 法 中 定义 容器 工厂 名 称 即 可 。TestProperties.CONTAINER_FACTORY (jersey.config.test.container.factory) 参数 的 值 设置 为 


Public class TIMyResourceJTFTest extends JerseyTest { 
static final String CONTAINER GRIZZLY = 
"org.glassfish.jersey.test.grizzly.GrizzlyTestContainerFactory"; 
static final String CONTAINER MEMORY = 
"org.glassfish.jersey.test.inmemory.InMemoryTestContainerFactory"; 
static final String CONTAINER JDK = 
"org.glassfish.jersey.test.jdkhttp.JdkHttpServerTestContainerFactory"; 
static final String CONTAINER SIMPLE = 
"org.glassfish.jersey.test.simple.SimpleTestContainerFactory"; 
QOverride 
protected Application configure() { 

set (TestProperties.CONTAINER FACTORY, CONTAINER SIMPLE); 

return new ResourceConfig (BookResource.class); 
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7.2 单元 测试 


简单 来 阅 ， 单 元 测试 就 是 对 源 代码 中 公有 方法 的 功能 性 测试 。 本 节 不 会 对 和 


7.2.1 集成 Spring 的 单元 测试 


第 一 个 难点 是 如 何在 单元 测试 中 使 


1. 依 赖 注入 


对 于 使 


元 测试 的 基本 概念 和 测试 方法 进行 详 述 


， 而 是 着 重 讲述 单元 测试 的 难点 。 


Spring 容 器 。Spring 提 供 了 相关 的 解决 方案 ， 可 以 在 测试 类 的 注解 中 指定 SpringJUnit4ClassRunner 来 实现 ， 下 面 开始 详细 描述 。 


依赖 注入 的 源 代码 ， 单 元 测试 最 常见 的 问题 是 被 测试 类 A 依赖 注入 了 B 类 ， 运 行 时 B 的 实例 总 是 空 指针 。 出 现 这 个 问题 是 因为 单元 测试 的 上 下 文中 没有 依赖 注入 容器 的 环境 。 以 Spring 作 为 依赖 


注入 容器 的 项 目 为 例 ，BookService 类 中 依赖 注入 了 BookDao 类 的 实例 ， 那 么 测试 代码 中 ，BookService 类 的 实例 就 不 能 直接 通过 构造 函数 创建 ， 否 则 这 个 BookService 实 例 就 不 是 Spring 容 器 管理 的 
Bean， 导 致 的 结果 就 是 BookDao 实 例 为 空 指针 。 示 例 代 码 如 下 。 


public class BookService { 
@Autowired 
privateBookDaobookDao; 
public Book saveBook 
(final Book book 


) { 


return bookDao .store 
(book 


} 
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这 种 


情况 下 ， 我 们 可 以 在 测试 类 中 使 


类 可 以 帮 


户 生 成 BookService 类 的 实例 ， 这 一 过 程 中 ，BookDao 类 的 实例 也 创建 好 并 存在 于 Spring 容器 中 了 。 单 元 测试 代码 使 


@RunWith 注 解 定义 SpringJUnit4ClassRunner 类 。 与 Jersey 测 试 框架 帮助 


户 管理 Spring 容器 。 通 过 @ContextConfiguration 注 解 定义 的 Spring 配置 文件 ，SpringJUnit4ClassRunne 


户 管理 测试 服务 器 和 客户 端 类 似 ，spring-test 包 提供 的 SpringJUnit4ClassRunner 


[实例 在 测试 类 启动 后 ， 帮 助 用 户 建立 起 了 Spring 容器 环境 ， 这 样 就 可 以 让 容器 帮助 用 


@Autowired 定 义 了 一 个 BookService 字 段 ， 其 余部 分 只 和 测试 用 例 有 关 。 示 例 代码 


如 下 。 


@ContextConfiguration (locations = { "classpath:applicationContext.xml" }) 


@RunWith (SpringJUnit4ClassRunner.class) 
public class TUMyServiceTest { 
@Autowired 
private BookService bookService; 
@Test 
public void testGetAndSave() { 
final Book result = bookService.getBook (1L); 
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在 使 


集成 Spring 的 项 目 中 ， 通 常 使 


@Transactional 注 解 存储 方法 ， 即 可 在 运行 时 F 


Spring 容器 提交 对 


JPA 的 项 目 时 ， 对 DAO 层 源 代码 的 测试 中 ， 一 个 常见 的 “ 怪 现象 ”是 明明 存储 一 个 实体 类 已 经 通过 ， 数 据 库 中 却 没有 这 条 记录 。 这 是 


为 JPA 需 要 显 式 地 提交 对 


务 ， 如 下 所 示 。 


务 才 会 将 数据 真正 写 入 数据 库 。 在 


@Repository 
public class BookDao { 
@Transactional 
public Book store 
(final Book entity 
) { 
return entityManager.merge 
(entity 
汪汪 


} 
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} 


但 是 ,项 目 中 的 业务 逻辑 不 总 会 允许 每 一 个 实体 的 存储 都 原子 地 提交 
情况 下 ， 对 DAO 层 的 单元 测试 再 次 陷入 到 “ 怪 现象 ”的 窘境 中 。 有 两 种 情况 可 以 忽 


有 意义 。 


如 果 存 储 测试 数据 是 我 们 的 单元 测试 所 必需 的 ， 那 么 只 有 在 测试 类 中 寻找 实现 引 


务 ， 而 是 当 A、B、C 都 成 功 保存 后 才 会 提交 
格 测 试 数据 的 持久 化 ， 一 种 是 使 


务 ， 否 则 回 滚 


务 。 


此 ，@Transactional 注 解 会 从 DAO 层 移 至 Service 层 。 这 种 


务 显 式 提交 的 办 法 。 这 种 情况 下 ， 我 们 可 以 使 


内 存 数据 库 (通常 ， 单 元 测试 应 该 这 样 做 ) ， 另 一 种 是 测试 逻辑 成 功 即 可 ， 测 试 数据 没 


@TransactionConfiguration 注 解 和 @Transactional 注 解 ， 如 下 所 示 。 


@ContextConfiguration (locations = { "classpath:context.xml", 


"classpath:context-persistence.xml", "classpath:context- 


transaction.xml" }) 


@TransactionConfiguration (transactionManager="xxxTransactionManager", 


defaultRollback=false) 
@Transactional 
@RunWith (SpringJUnit4ClassRunner.class) 
public class TITestXxxDao { 
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} 


7.2.2 异步 测试 


mh 


元 测试 中 第 二 个 难点 是 对 实现 异步 功能 


从 编码 上 解决 异步 使 


源 代码 进行 测试 。 一 个 常见 的 现象 是 被 测试 的 线程 还 在 进行 中 ， 而 测试 


线程 已 经 结束 。JUnit 框 架 同步 测试 的 扩展 可 以 从 编码 和 架构 上 解决 。 


第 8 章 将 要 讲述 的 Java 并 发 技术 。 例 如 ， 在 主线 程 中 使 


线程 或 使 用 线程 池 来 测试 异步 程序 。 
单元 测试 时 应 当 排除 这 部 分 用 例 。 一 个 通 


的 做 法 是 使 


步 测试 代码 的 编写 相对 难度 大 些 ， 但 可 以 快速 解决 对 功能 模块 的 和 
Maven 定 制 profile 来 隔离 不 同 的 测试 用 例 。 


的 场景 ; 编码 解决 更 轻 量 和 灵活 ， 但 不 具有 通用 性 。 


架构 上 可 以 选择 JUnit 的 第 三 方 扩展 包 来 支持 多 线程 测试 ， 这 超出 了 本 书 的 范围 


全 阅读 指导 “异步 测试 的 示例 可 参考 第 8 章 的 示例 项 目 : jax-rs2-guide\sample\8\asyn-test。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/8/asyn-rest。 


7.3 ”集成 测试 


， 读 者 可 参考 JUnit 扩 展 的 相关 资料 。 


Future 和 同步 器 来 阻塞 主线 程 ， 直 到 被 测试 的 线程 结束 (代码 的 实现 可 参考 第 8 章 相关 示例 ) 。 也 可 以 在 测试 用 例 中 创建 
元 测试 ， 需 要 读者 仔细 揣摩 。 这 里 要 说 明 的 是 ， 异 步 单元 测试 用 例 通常 比较 耗 时 ， 因 此 在 全 量 执行 


从 实际 开发 和 单元 测试 经 验 上 看 ， 架 构 层面 的 解决 方案 更 


E 量 级 ， 适 合 团队 规定 使 


集成 测试 是 系统 运行 时 的 功能 测试 ， 是 对 组 件 、 模 块 之 间 联 合 工作 的 测试 。REST 应 用 的 集成 测试 就 是 对 系统 公开 的 资源 地 址 的 功能 性 测试 。 运 行 时 测试 依赖 于 测试 服务 器 。 根 据 笔者 经 验 ， 测 试 服务 器 


的 建立 与 启动 可 以 分 为 3 类 。 


第 一 类 是 使 


第 二 类 是 使 用 Maven 插 件 启动 外 置 服务 器 。 这 种 方式 通过 在 项 
阶段 停止 ， 可 参考 第 2 章 关 于 Servlet 容 器 应 用 一 节 。 


如 上 所 述 的 内 置 HTTP 容 器 。 这 种 方式 通过 JUnit 测 试 类 直接 定义 测试 服务 器 或 者 继承 Jersey 测 试 框架 类 


erseyTest， 使 


在 执行 测试 前 加 载 配置 并 启动 服务 ， 在 测试 用 例 完成 后 停止 服务 。 


的 Maven 配 置 文件 pom.xml 中 定义 测试 服务 器 ， 使 其 在 Maven 生 命 周 期 的 pre-integration-test 阶 段 启动 ， 并 在 post-integration-test 


以 上 两 种 方式 都 无 须 部 署 (deploy) 到 测试 服务 器 。 第 三 类 是 将 项 目 打包 部 署 到 和 生产 环境 相同 的 集成 测试 环境 ， 其 优点 是 可 以 模拟 真实 场景 ， 以 完成 对 系统 功能 性 和 非 功 能 性 的 测试 ， 而 缺点 是 打包 


部 署 占 


7.4 日 志 增 强 


在 测试 日 志 中 ，Jersey 测 试 框架 提供 了 输出 通信 过 程 中 的 传输 


public class TIMyResourceJTFTest extends JerseyTest { 
QOverride 
protected Application configure() { 

enable (TestProperties.LOG TRAFFIC);// 


关注 点 1 
: 启用 传输 日 志 
enable (TestProperties.DUMP ENTITY); 


了 集成 测试 的 时 间 。 典 型 的 Servlet 容 器 是 Tomcat，Java EE 容器 是 GlassFish， 可 参考 第 2 章 关 于 Servlet 容 器 应 


志 信 息 。 在 测试 代码 中 


//set (TestProperties. CONTAINER FACTORY 1 CONTAINER SIMPLE); 


已 


4 
一 站。 


这 一 功能 是 通过 覆盖 JerseyTest 类 的 configure() 方 法 并 加 入 关注 点 1 这 一 行 ， 示 例 代 码 如 下 。 


return new ResourceConfig (BookResource.class); 
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bE: 


这 样 一 来 ， 测 试 过 程 中 输出 的 信息 将 包括 传输 日 志 ， 可 参考 下 面 的 输出 。 在 启用 传输 日 志 后 ， 可 以 启用 实体 日 志 来 输出 传输 过 程 中 的 实体 信息 ， 可 参见 下 面 代码 中 最 后 一 段 所 示 的 XML 格 式 的 数据 。 


1 > GET http://localhost:9998/books/ 

2 < 200 

2 < Date: Tue, 22 Oct 2013 03:24:46 GMT 

2 < Content-Length: 496 

2 < Content-Type: application/xml 

<?xml Version="1.0" encoding="UTF-8" standalone="yes"?><books><bookList><book bookId="1" 
bookName="Java Restful Web Service 

使 用 指南 " publisher="cmpbook"/><book bookId="2" 
bookName="JSF2 

和 RichFaces4 

使 用 指南 " publisher="phei"/></bookList></books> 


7.5 本章 小 结 


本 章 详细 讲述 了 Jersey 的 测试 框架 及 其 在 单元 测试 和 集成 测试 中 的 使 用 。 单 元 测试 主要 考虑 依赖 注入 和 事务 这 两 个 技术 点 如 何 和 生产 环境 保持 一 致 。 集 成 测试 主要 考虑 如 何 部 署 测 试 环 境 ， 使 之 尽量 贴 
近 生 产 环 境 。 最 后 介绍 了 Jersey 测 试 框架 对 日 志 信息 的 增强 。 下 一 章 ， 我 们 开始 讲述 REST 的 服务 器 端 推送 技术 和 异步 通信 。 


第 8 章 ”REST 推 送 与 异步 通信 


本 章 分 为 两 部 分 ， 前 半 部 分 讲述 REST 通 信 中 有 关 服 务 器 推送 事件 的 技术 ， 后 半 部 分 讲述 REST 的 异步 通信 和 JAX-RS 2.0 定 义 的 异步 请 求 处 理 规范 。 


8.1 ”服务 器 一 浏览 器 通信 


服务 器 一 浏览 器 通信 也 可 称 为 服务 器 端 推送 技术 ， 是 一 种 当 服务 器 端的 业务 数据 、 资 源 状态 发 生 改 变 时 ， 服 务 器 可 以 主动 将 这 一 信息 通知 给 相关 的 浏览 器 的 通信 技术 。 如 果 服务 器 与 客户 端 使 用 TCP/IP 
协议 建立 连接 ， 这 样 的 Socket 通 信 并 无 特别 之 处 ， 一 旦 连接 建立 ， 在 这 样 的 双向 通信 链 路 中 随时 都 可 以 发 送 通知 。 然 而 ，REST 通 信 是 基于 HTTP 的 通信 ， 而 HTTP 是 无 状态 的 通信 协议 ， 每 一 次 请 求 一 响应 都 
是 基于 一 个 新 建立 的 HTTP 连 接 ， 这 就 使 服务 器 主动 通知 浏览 器 成 为 一 个 难点 。 这 是 因为 在 基于 请 求 一 响应 模式 下 ， 服 务 器 的 角色 是 被 动 应 答 ， 无 法 主动 通知 浏览 器 ; 另 一 个 原因 是 ， 每 次 请 求 后 HTTP 连 接 
断 开 ， 服 务 器 无 法 再 获取 客户 端的 地 址 ， 也 就 是 无 法 将 通知 发 送 给 浏览 器 端 。 


为 了 解决 这 一 问题 ， 人 们 尝试 过 很 多 基于 请 求 一 响应 模式 的 变通 办 法 ， 总 结 起 来 有 两 种 途径 。 第 一 种 是 由 浏览 器 周期 性 地 主动 去 服务 器 获取 ， 使 用 “ 拉 ” 的 方式 模拟 服务 器 的 “ 推 ”; 要 么 在 请 求 处 理 
结束 后 ， 服 务 器 返回 响应 但 不 关闭 这 条 连接 ， 直 到 服务 器 将 业务 数据 的 变化 响应 给 浏览 器 ， 最 后 将 连接 关闭 。 第 二 种 方式 并 没有 破坏 请 求 一 响应 模式 ， 而 是 将 响应 分 成 了 两 个 阶段 。 这 两 种 方式 都 存在 着 让 
开发 者 头疼 的 问题 ， 处 理 不 好 会 给 产品 日 后 的 维护 带 来 问题 。 


先 回 到 REST 中 ， 这 些 HTTP “通病 ”会 在 后 面 结合 着 REST 实 践 给 出 解决 方案 。 和 MVC 一 样 ， 服 务 器 一 浏览 器 通信 在 JAX-RS 2.0 中 并 没有 相关 规范 的 定义 ， 但 是 和 MVC 与 REST 平 行 的 关系 不 同 的 
是 ，SSE (Server-Sent Events， 服 务 器 端 推送 事件 ) 这 项 技术 对 实现 REST 式 的 Web 服 务 的 功能 性 和 性 能 颇具 影响 。 因 此 ， 本 书 将 其 收录 并 作为 一 个 小 节 讲述 ， 本 章 将 基于 上 述 提出 的 两 种 解决 方案 ， 详 述 
如 何在 项 目 中 实现 这 一 通信 技术 。 


8.1.1 Polling 技 术 
服务 器 一 浏览 器 通信 技术 的 第 一 种 解决 方案 是 客户 端 轮 询 技术 ， 即 Polling。 


1. 简 述 


客户 端 轮 询 技术 (Polling) 相对 其 他 方案 ， 最 原始 、 易 行 ， 即 浏览 器 周期 性 地 主动 访问 服务 器 的 特定 地 址 ， 以 获取 服务 器 端 数 据 状态 的 变化 。 如 图 8-1 所 示 ， 通 常 来 说 ， 在 浏览 器 端 使 用 JavaScript 脚 本 
启动 一 个 定时 任务 ,该 任务 向 服务 器 发 送 请 求 并 获取 资源 状态 。 如 果 服 务 器 端 特定 数据 发 生变 化 ， 那 么 会 将 变化 信息 响应 给 客户 端 ， 客 户 端 使 用 响应 的 数据 泻 染 界 面 ， 为 用 户 做 出 及 时 的 反馈 。 
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| 

periodically ' polling 
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图 8-1 客户 端 轮 询 示 意图 


2. 优 点 与 缺点 


优点 : 客户 端 轮 询 技术 易于 实现 。 不 需要 为 此 在 服务 器 端 或 者 浏览 器 端 额外 使 用 任何 第 三 方 的 库 ， 开 发 者 容易 理解 ， 使 用 现 有 技术 和 工具 就 可 以 实现 。 客 户 端 轮 询 技术 对 设计 没有 注入 性 污染 。 选 择 技 
术 架 构 和 设计 、 实 现 业 务 逻 辑 时 ， 这 种 方式 可 以 即 插 即 拔 ， 不 会 污染 业务 平台 中 结构 性 的 代码 。 


缺点 : 客户 端 轮 询 技术 的 缺点 是 显而易见 的 ， 轮 询 中 的 每 次 请 求 一 响应 过 程 都 需要 建立 新 的 HTTP 连 接 并 在 结束 时 关闭 该 连接 。 这 就 造成 两 大 问题 。 


第 一 ， 如 果 服 务 器 端的 业务 数据 在 两 次 定时 任务 发 起 的 请 求 过程 中 没有 变化 ， 后 一 次 请 求 的 做 功 实际 为 负数 一 一 浪费 了 服务 器 端的 带宽 ， 而 且 没有 获得 有 效 负载 。 


第 二 ， 也 是 最 让 开发 者 纠结 的 事情 ， 即 浏览 器 端的 定时 器 间隔 时 间 参 数 的 设置 。 由 于 需要 及 时 获取 服务 器 端的 业务 数据 的 状态 ， 这 个 定时 间隔 参数 设置 不 宜 过 长 ， 但 是 过 短 又 会 频 发 第 一 个 问题 。 因 
此 ， 间 隔 时 间 的 设置 是 个 比较 尴 众 的 问题 ， 因 为 在 编码 和 调试 阶段 定义 并 运行 完好 的 参数 ， 很 难 和 生产 环境 吻合 ， 甚 至 开发 阶段 有 可 能 疏漏 或 无 法 覆盖 全 部 生产 环境 中 的 业务 场景 。 还 有 一 个 让 人 难受 的 地 
方 是 ， 这 种 请 求 的 代码 很 难 抽象 出 来 ， 因 为 不 同业 务 的 定时 间隔 都 是 一 个 独立 的 经 验 值 。 


8.1.2 Comet 技 术 
Comet 是 反 向 AJAX 的 技术 集 ， 包 括 长 轮 询 (Long Polling) 和 流 (Streaming) 两 种 技术 实现 。 


1. 简 述 


什么 是 反 向 AJAX 呢 ? 要 了 解 反 向 AJAX， 要 先 从 AJAX 说 起 。 


AJAX 技 术 是 指 从 浏览 器 端 向 服务 器 端 发 起 的 异步 请 求 ， 已 经 广为人知 ，8.1.1 节 所 述 的 Polling 就 是 AJAX 的 实践 。 概 括 地 说 ， 浏 览 器 发 起 的 请 求 是 通过 脚本 实现 的 ， 页 面 并 没有 提交 或 者 跳 转 ， 请 求 由 服 
务 器 处 理 并 返回 响应 数据 后 ， 浏 览 器 处 理 响应 数据 并 将 这 一 变化 泻 染 到 HTML 中 的 DOM 树 ，HTML 页 面 的 标签 值得 到 了 更 新 ， 实 现 了 页 面 的 局 部 刷新 。 


反 向 AJAX (Reverse AJAX) 技术 从 请 求 方向 看 并 没有 做 到 反 向 ， 因 为 基于 请 求 一 响应 模式 下 的 HTTP 请 求 本 质 上 无 法 做 到 反 向 。 这 个 “ 反 向 ”是 从 实现 结果 上 看 的 ， 即 从 服务 器 端 (通过 保持 连接 的 
HTTP 通 道 ) 向 客户 端 发 送 数据 ， 以 实现 低 延 迟 地 通知 客户 端的 技术 。 反 向 AJAX 技 术 是 服务 器 一 浏览 器 通信 技术 的 第 二 种 解决 方案 ， 其 底层 实现 依赖 于 HTTP 连 接 不 能 断 开 这 一 前 提 条 件 。 长 轮 询 和 流 技术 是 
反 向 AJAX 的 两 种 技术 手段 ， 通 信 原 理 相同 。 长 轮 询 示意 图 如 图 8-2 所 示 。 


如 图 8-2 所 示 ， 长 轮 询 通过 keepAlive 使 HTTP 连 接 得 以 保持 。 为 什么 要 保持 连接 呢 ? 因为 在 请 求 发 出 后 的 一 定时 间 内 ， 服 务 器 一 直 没有 做 出 响应 ， 该 连接 会 因 连接 超时 而 断 开 。Comet 利 用 HTTP 1.1 的 
keepAlive 持 久 性 连接 技术 ， 在 浏览 器 发 出 请 求 后 ， 通 过 keepAlive 保 持 服务 器 向 浏览 器 做 出 响应 的 通信 。 这 样 一 来 ， 就 解决 了 连接 超时 断 开 的 问题 。 那 么 ， 连 接 的 关闭 就 只 有 两 种 情况 ， 一 种 是 浏览 器 主动 
断 开 ， 另 一 种 是 服务 器 端 特定 数据 发 生变 化 ， 并 将 这 一 信息 响应 给 浏览 器 ， 主 动 断 开 连 接 来 完成 请 求 一 响应 模式 的 一 次 请 求 。 


Comettlong polling) 


| 
| 
一 一 一 一 一 一 "COnneci0n 0pen-————3| 


| 

| 
rest requesit 一 一 一 一 一 

~、 


本 


Long-polling 


a 二 


| 
| | 


Tesponse 


======CO0NEction dose ==== | 


一 一 一 了] 一 一 一 一 


图 8-2 ”长 轮 询 示意 


相 比 Polling， 实 现 Comet 要 困难 得 多 ， 服 务 器 端 和 浏览 器 端 都 需要 第 三 方 的 库 来 支持 这 一 技术 。Atmosphere 库 和 CometD 库 是 实现 Comet 技 术 的 第 三 方 工具 包 ，Jersey 并 没有 提供 支持 Comet 实 现 的 
包 ， 本 书 也 不 会 对 Comet 的 实现 做 进一步 讨论 ， 但 读者 要 清楚 Comet 技 术 是 这 个 领域 的 一 个 选择 。 


2 优点 与 缺点 


优点 : 反 向 AJAX 的 技术 解决 了 Polling 低 效 地 消耗 服务 器 的 网 络 带 宽 和 系统 负载 的 问题 。 同 时 ， 由 于 服务 器 主动 向 浏览 器 发 送 数 据 ， 因 此 有 很 好 的 低 延 迟 性 。 


缺点 : Comet 需 要 服务 器 端 额外 的 技术 实现 来 支持 ， 同 时 需要 在 服务 器 和 浏览 器 两 端 引 入 第 三 方 工具 包 ， 实 现 相 对 复杂 。 


8.1.3 SSE 技术 


SSE 是 HTML5 技 术 集 的 一 部 分 ， 定 义 了 服务 器 推送 技术 的 标准 规范 。 


1. 简 述 


SSE 规 范 的 地 址 是 http://dev.w3.org/html5/eventsource。 其 核心 是 基于 EventSource 接 口 的 事件 监听 机 制 ， 包 括 onopen、onmessage 和 onerror 三 个 事件 监听 器 。SSE 服 务 器 端 响应 数据 的 媒体 类 型 
(Content-Type) 是 text/event-stream。Jersey 的 媒体 库 提供 了 对 SSE 的 支持 ， 可 参见 8.2 节 相关 内 容 。 


2. 优 点 与 缺点 


优点 : SSE 是 标准 规范 一 一 HTML5 标 准 之 一 ， 具 备 编程 语言 的 无 关 性 。 首 先 ，SSE 支 持 跨 语言 的 开发 ， 无 论 具 体 使 用 什么 语言 和 框架 ， 只 要 按照 以 EventSource 接 口 为 中 心 ， 完 成 事件 监听 机 制 即 可 实 
现 SSE。 其 次 ，SSE 支 持 跨 语言 的 调用 ， 这 点 很 好 理解 ， 正 是 基于 标准 接口 和 标准 事件 监听 ， 七 层 协 议 上 的 HTTP 包 很 容易 被 各 系统 彼此 阅读 。SSE 的 代码 实现 和 交互 逻辑 相对 简单 ， 在 Java EE 生态 环境 中 ， 
得 到 了 Jersey 提 供 的 支持 。 


缺点 : 由 于 请 求 一 响应 模型 的 限制 ，SSE 和 Comet 一 样 ， 是 一 种 从 服务 器 端 到 浏览 器 端的 单 向 通信 ， 浏 览 器 无 法 在 同一 条 连接 上 做 出 二 次 请 求 或 者 对 服务 器 的 响应 做 出 “响应 ”， 这 一 缺点 无 法 支持 复 
杂 的 交互 需求 。 另 外 ，SSE 标 准 和 Jersey-sse 支 持 包 都 还 在 不 断 完善 中 (Jersey 提 供 持续 升级 的 SSE 支 持 包 ， 但 这 并 不 意味 着 当前 版 本 不 稳定 ) 。 


8.1.4 WebSocket 技 术 


Websocket 是 HTML5 技 术 集 的 一 部 分 ， 它 提供 了 一 个 双向 的 、 在 一 条 TCP 信 道中 的 客户 端 和 服务 器 之 间 全 双 工 的 通信 。 


1. 简 述 


WebSocket 消 除了 所 有 与 HTTP 连 接 的 无 状态 特性 相关 的 限制 。Java EE 7 已 经 支持 WebSocket， 其 参考 实现 是 GlassFish 项 目的 Tyrus 子 项 目 (项 目地 址 是 https://tyrus.java.net) 。 本 书 不 会 对 
WebSocket 的 实现 做 进一步 讲述 ， 推 荐 读者 阅读 来 自 Oracle 的 布道 者 Arun Gupta 所 著 的 《Java EE 7 Essentials》 一 书 的 第 7 章 内 容 。 


2. 优 点 与 缺点 


优点 : WebSocket 是 标准 规范 一 HTML5 标 准 之 一 ， 逐 渐 开 始 流行 。 其 功能 强大 、 性 能 突出 : 双向 、 双 工 通信 。 


缺点 : 相对 于 SSE 的 实现 ，WebSocket 较 为 复杂 。 


8.2 ”SSE 详 述 


从 8.1 节 对 上 述 4 种 服务 器 端 推送 技术 的 分 析 中 ， 我 们 清楚 了 服务 器 一 浏览 器 通信 和 是 什么 和 怎么 做 。 我 们 的 中 心思 想 是 如 何 提高 基于 Jersey 的 应 用 的 性 能 ， 因 此 ， 本 节 结 合 REST 式 的 Web 服 务 ， 就 服务 器 
端 推送 事件 (SSE) 技术 进行 详细 讲述 。 


全 冶 读 指导 8.2 节 示例 所 在 目录 是 jax-rs2-guide\sample\8\sse。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/8/sse。 


8.2.1 Java 并 发 


在 REST 的 异步 调用 和 测试 中 ， 会 经 常 使 用 JDK 1.6+ 提 供 的 Future 和 Synchronization (同步 器 ) 来 保证 异步 、 并 发 线程 能 够 按照 既定 的 顺序 执行 。 因 此 ， 掌 握 JDK 的 异步 执行 接口 Future 和 同步 器 的 使 
是 十 分 必要 的 。 本 节 ， 将 对 JDK 1.6+ 提 供 的 Future 和 4 种 同步 器 逐一 讲述 。 


1.Future 


Future 接 口 是 JDK 1.5 提 供 的 用 于 处 理 异 步 线程 的 接口 。 该 接口 定义 了 一 个 泛 型 类 型 ， 该 类 型 是 get() 方 法 的 返回 类 型 。get() 方 法 用 于 执行 一 个 实现 了 Callable 接 口 的 线程 ， 并 获取 其 执行 结果 ， 作 为 
get() 的 返回 值 。 
(1) Callable 


Callable 接 口 是 JDK 1.5 提 供 的 用 于 执行 任务 的 线程 接口 ， 是 Runnable 接 口 的 增强 (两 者 没有 直接 的 依赖 关系 ) 。Runnable 接 口 定义 的 run0 用 于 执行 线程 任务 ， 但 没有 返回 值 ，Callable 接 口 定义 了 一 
个 泛 型 类 型 ， 该 类 型 是 接口 方法 call() 的 返回 类 型 。call() 方 法 执行 线程 任务 后 ， 返 回 泛 型 类 型 的 对 象 。 
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8-3 ”FutureTask 继 承 关系 示意 图 


(2) FutureTask 


FutureTask 类 的 字面 意思 是 “未 来 的 任务 ”， 是 一 个 结合 了 Runnable 接 口 和 Future 接 口 的 实现 类 ， 如 图 8-3 所 示 。 


FutureTask 用 于 处 理 可 取消 的 异步 任务 。FutureTask 的 get() 方 法 用 于 获取 任务 执行 结果 ， 如 果 任 务 尚未 完成 ， 则 阻塞 get() 方 法 直至 任务 完成 。FutureTask 的 run() 方 法 用 于 执行 任务 ， 任 务 一 旦 完成 就 
不 能 重新 开始 或 取消 。 它 有 三 个 状态 : 等 待 (waiting to run) 、 运 行 (running) 和 完成 (completed) 。 


同步 器 用 于 在 多 线程 之 间 同 步 状 态 ，JDK 根 据 不 同 的 使 用 场景 ， 提 供 了 如 下 4 种 同步 器 。 


(1) Semaphore 同 步 器 


Semaphore 的 字面 意思 是 “信号 ” ， 通 过 内 部 计数 器 控制 一 组 线程 在 同一 时 间 对 某 一 特定 资源 的 访问 ， 或 者 控制 一 组 线程 对 执行 某 个 操作 的 权限 。Semaphore 的 acquire() 方 法 会 使 计数 器 数值 递减 ， 


如 果 计 数 器 归 零 ， 则 请 求 线程 被 阻塞 ， 直 到 计数 器 重新 可 以 递减 到 零 。Semaphore 的 release() 方 法 会 使 计数 器 数值 递增 ， 从 而 可 能 释放 一 个 正在 阻塞 的 线程 。Semaphore 通 常用 于 限制 可 以 访问 某 些 资源 
(物理 或 逻辑 的 ) 的 线程 数目 。 


(2) CountDownLatch 同 步 器 


CountDownLatch 从 字面 上 可 以 理解 为 一 个 带 有 Count (计数 器 ) 的 Latch ( 门 门 ) ， 在 初始 化 后 执行 countDown() 操 作 来 控制 多 个 线程 的 同步 。CountDownLatch 通 过 内 部 的 计数 器 控制 所 有 线程 处 
于 等 待 ， 直 到 其 计数 器 归 零 后 ， 所 有 线程 一 起 执行 后 续 任 务 。 在 所 有 线程 都 能 通过 之 前 ， 每 个 线程 通过 CountDownLatch 的 await( 方 法 (可 以 设置 等 待 超 时 时 间 ) 等 待 。CountDownLatch 的 计数 器 无 法 
被 重 置 。 如 果 需 要 重 置 计数 ， 那 么 可 以 考虑 使 用 CyclicBarrier。 


CountDownLatch 的 应 用 场景 举例 如 下 : 


1) 在 一 个 资源 初始 化 之 前 ， 使 用 该 资源 的 所 有 活动 都 处 于 等 待 。 


2) 在 释放 一 个 服务 之 前 ， 完 成 所 有 依赖 于 该 服务 的 任务 。 
3) 在 开始 多 人 游戏 之 前 ， 确 保 所 有 参与 者 的 终端 都 连接 完毕 。 


(3) CyclicBarrier 同 步 器 


CyclicBarrier 的 字面 意思 是 循环 使 用 的 Barrier (路 障 ) 。CyclicBarrier 通 过 内 部 的 计数 器 控制 所 有 线程 互相 等 待 ， 直 到 到 达 某 个 公共 路 障 点 (Common Barrier Point) 。 在 涉及 一 组 固定 大 小 的 线程 的 
程序 中 ， 这 些 线程 必须 不 时 地 互相 等 待 ， 此 时 CyclicBarrier 很 有 用 。 因 为 该 Barrier 在 释放 等 待 线程 后 可 以 重用 ， 所 以 称 它 为 循环 使 用 的 Barrier。 


CountDownLatch 用 来 等 待 事件 ， 当 计数 器 递减 归 零 时 ， 被 CountDownLatch 的 await() 方 法 阻塞 的 线程 继续 执行 后 续 任 务 ; CyclicBarrier 用 来 等 待 其 他 线程 ， 当 await() 方 法 使 计数 器 递增 的 数量 到 达 
设 定 数量 后 ， 被 CyclicBarrier 的 await() 方 法 阻塞 的 线程 继续 执行 后 续 任 务 。 


(4) Phaser 同 步 器 


Phaser 是 JDK 1.7 提 供 的 同步 器 ， 其 作用 和 CountDownLatch、CyclicBarrier 类 似 ， 但 Phaser 的 使 用 方式 更 为 灵活 。Phaser 使 用 register (注册 ) 方法 来 递增 计数 器 ， 使 用 arriveAndDeregister() 方 法 
来 递减 计数 器 ， 使 用 arriveAndAwaitAdvance() 方 法 来 阻塞 线程 ， 该 阻塞 在 Phaser 的 计数 器 归 零 时 唤醒 线程 继续 执行 后 续 任务 。 


另外 ，JDK 提 供 Exchanger (交换 器 ) 类 用 于 两 个 线程 共享 资源 并 允许 它们 交换 执行 任务 。Exchanger 在 REST 的 场景 中 并 不 常用 。 


3. 并 发 数据 结构 


JDK 提 供 了 包括 数组 、 链 表 、 队 列 和 键 值 对 等 丰富 的 线程 安全 的 并 发 数据 结构 。 在 每 个 数据 结构 内 部 ， 通 过 细 粒 度 的 锁 或 原子 操作 ， 确 保 内 部 的 数据 在 多 线程 同时 引用 并 操作 时 ， 逻 辑 上 的 正确 性 。 由 
于 本 书 的 内 容 和 篇 幅 所 限 ， 无 法 列举 JDK 提 供 的 全 部 并 发 数据 结构 ， 在 此 只 简 述 本 书 示 例 中 涉及 的 队列 接口 BlockingQueue 的 并 发 特性 。BlockingQueue 接 口 操作 见 表 8-1。 


表 8-1 lockingQueue 接 口 操作 
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如 表 8-1 所 示 ，“ 抛 出 异常 ” 列 ， 在 并 发 场景 中 ， 当 前 线程 的 操作 无 法 执行 时 直接 抛 出 异常 。“ 特 殊 值 ” 列 ， 当 操作 无 法 执行 时 返回 nul 或 者 false。 “阻塞 ” 列 ， 当 操作 无 法 执行 时 会 阻塞 调用 线程 ， 直 
至 操作 执行 完毕 。“ 超 时 ” 列 ， 当 操作 无 法 执行 时 ， 会 在 超时 时 间 内 阻塞 调用 线程 ， 超 时 后 放弃 操作 。 


8.2.2 SSE 流程 


Jersey 的 SSE 支 持 包 jersey-media-sse 基 于 HTML5 的 SSE 规 范 ， 提 供 了 一 套 支持 SSE 规 范 的 完整 的 APl。Maven 依 赖 包 定义 如 下 。 


<dependency> 
<groupId>org.glassfish.jersey.media</groupId> 
<artifactId>jersey-media-sse</artifactId> 
</dependency> 


Jersey 的 SSE 支 持 包 提供 两 种 通信 模式 ， 即 发 布 一 订阅 模式 和 广播 模式 。 前 者 是 一 种 端 到 端的 通信 ， 后 者 是 多 播 通信 。 接 下 来 我 们 分 别 讲述 这 两 种 模式 。 


1 .发 布 一 订阅 模式 


发 布 一 订阅 模式 的 APIl 和 典型 的 工作 流程 描述 如 图 8-4 所 示 。 


根据 SSE 标 准 规范 定义 的 EventSource 接 口 ，Jersey SSE 定 义 了 EventListener 接 口 及 其 实现 类 EventSource。SSE 的 实现 流程 描述 如 下 : 


第 一 步 ， 在 客户 端 创建 EventSource 实 例 并 覆盖 onEvent( 方 法 。onEvent() 方 法 用 来 处 理 服务 器 端 推 送 事 件 ， 输 入 参数 为 InboundEvent ( 进 站 事件 ) 。EventSource 构 造 函 数 的 输入 参数 为 一 个 
WebTarget 端 点 ， 指 向 服务 器 端的 资源 路 径 为 sse 的 GET 方 法 ， 该 方法 使 用 了 注解 @Produces (SseFeature.SERVER_SENT_EVENTS) 。 在 EventSource 实 例 化 过 程 中 ， 如 图 8-4 中 国 所 示 ， 会 从 这 个 端点 向 
服务 器 发 出 请 求 并 指明 接收 数据 的 媒体 类 型 为 gseFeature.SERVER_SENT_EVENTS， 即 Accept 头 信息 声明 为 text/event-stream 类 型 。 


EventSource * EventListener Accept “textlevent-stream" 


InboundEvent 


InboundEventReader * 
Ceaaams MessageBo eader<“InboundEvenit> 


OutboundEventWiriter * 
MessageBodyWriter<OutboundEvent> 


OutboundEvent 


客户 普 服务 器 端 


图 8-4 Jersey 实现 SSE 流 程 示意 图 


第 二 步 ， 请 求 被 服务 器 接收 后 ， 开 启 SSE 事 件 通信 通道 ， 方 向 是 从 服务 器 端 向 客户 端 ， 并 返回 响应 给 客户 端 。 此 时 ，HTTP 保 持 连 接 ， 并 没有 关闭 ， 如 图 8-4 中 @ 所 示 。 


SSE 事 件 通信 通 道 的 客户 端 一 端 建立 Eventlnput 信 道 ， 用 于 读 取 InboundEvent ( 进 站 事件 ) 。Eventlnput 类 继承 自 Chunkedlnput，Chunkedlnput 人 允许 将 数据 在 一 条 信道 中 分 次 传输 ; Eventlnput 
类 的 泛 型 类 型 为 InboundEvent， 即 上 述 的 onEvent() 方 法 待 处 理 的 类 型 。 当 进 站 事件 到 达 时 ，MessageBodyReader 的 SSE 实 现 类 InboundEventReader 将 解析 数据 并 反 序 列 化 为 InboundEvent 类 型 的 数 
据 。 


SSE 事 件 通信 通 道 的 服务 器 一 端 建立 EventOutput 信 道 ， 用 于 写 入 OutboundEvent (出 站 事件 ) 。EventOutput 类 继承 自 ChunkedOutput，ChunkedOutput 人 允许 在 发 送出 站 事件 后 ，HTTP 连 接 通过 
HTTP 1.1 的 Keep-Alive 保 持 连接 ， 出 站 事件 写 入 HTTP 响 应 头 后 ，EventOutput 信 道 等 待 更 多 的 服务 器 推送 事件 。 出 站 事件 的 序列 化 写 入 ， 由 MessageBodyWriter 的 SSE 实 现 类 OutboundEventWriter 完 
成 。 


接 下 来 的 三 个 步骤 是 在 这 个 信道 上 完成 的 。 第 三 步 如 图 8-4 中 @ 所 示 ， 客 户 端 向 服务 器 发 送 POST 请 求 。 第 四 步 如 图 8-4 中 @ 所 示 ， 服 务 器 端 接收 后 会 向 EventOutput 信 道 写 入 数据 。 最 后 ， 如 图 8-4 中 @ 
所 示 ， 客 户 端 监听 到 信道 中 有 数据 到 达 ， 将 读 取 并 处 理 推送 事件 。 


到 此 ， 服 务 器 推送 事件 的 流程 执行 完 一 遍 。 信 道 的 连接 可 以 由 服务 器 主动 关闭 ， 或 者 由 客户 端 请 求 关闭 。 关 闭 时 机 可 以 由 业务 灵活 控制 。 


2. 广 播 模式 


通过 上 述 的 发 布 一 订阅 模式 ， 我 们 对 Jersey 的 SSE 支 持 包 和 通信 机 制 有 了 比较 全 面 的 了 解 。 广 播 模式 与 发 布 一 订阅 模式 相 比 ， 客 户 端的 实现 相同 ， 服 务 器 端 推送 事件 的 写 入 从 端 到 端的 Eventlnput 信 道 
换 成 了 多 点 广播 类 SseBroadcaster。SseBroadcaster 类 继承 自 Broadcaster 类 ， 泛 型 类 型 为 DutboundEvent (出 站 事件 ) 。SseBroadcaster 类 提供 了 一 次 关闭 多 点 信道 的 方法 closeAll0， 可 以 根据 业务 需 
要 ， 在 完成 广播 事件 后 执行 。 


如 图 8-5 所 示 ，Jersey-sse 包 中 的 成 员 类 都 已 经 一 一 介绍 。 


日 [而 Maven: org.glassfish.jersey.media:jersey-media-sse:2,3, 1 
: 日 目 jersey-media-Sse-2,3.1,jar (library home) 
由 META-INF 
日 Ea org.glassfish,jersey.media.sse 
… 仿 量 EventInput 
(Eh 。 EventInputReader 
I EventListener 
(hb EventOutput 
(EB b EventSource 


(EB b InboundEvent 

‘ca 5 InboundEventReader 
[sa localization.properties 
‘ca 也 LocalizationMessages 
| ‘ca 由 Du 也 oundEvent 


(Eh 。 OutboundEventWriter 
(Eh b SseBroadcaster 
(EB b SseFeature 


图 8-5 Jersey 的 SSE 实 现 包 示 意图 


到 此 ，Jersey 的 SSE 支 持 包 讲述 完毕 。 接 下 来 将 讲述 如 何 使 用 Jersey 的 SSE 支 持 包 来 实践 上 述 两 种 模式 。 
8.2.3 SSE 实现 


在 我 们 的 REST 应 用 中 使 用 Jersey 实 现 SSE 的 过 程 可 以 概括 为 两 个 环节 ， 第 一 个 环节 是 基于 本 章 上 述 理论 开发 新 的 或 维护 已 有 的 : REST 入 口 类 Application、 资 源 类 以 及 单元 测试 类 ; 第 二 个 环节 是 集成 测 
试 ， 目 的 是 验证 资源 方法 的 功能 。 


OE 823 节 示 例 所 在 目录 是 :jax-rs2-guide\sample\8\sse 
源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/8/sse 
1.Application 类 


支持 SSE 的 REST 应 用 入 口 类 AirResourceConfig 是 Application 类 的 子 类 ， 示 例 代 码 如 下 。 


QApplicationPath ("/event/*")// 
关注 点 1 


: 为 SSE 

定义 资源 路 径 

public class AirResourceConfig extends ResourceConfig { 
public AirResourceConfig() { 


oe 
关注 点 2 
: 注册 Feature 
和 资源 类 
super (SseFeature.class, AirSsePubSubResource.class, 

AirSseBroadcastResource.class); 

} 
} 


在 这 段 代码 中 ， 定 义 了 SSE 服 务 的 根 资源 路 径 为 /event/*， 见 关注 点 1。 手 动 注册 了 SseFeature 类 (在 Jersey 2.8 版 本 之 后 可 以 自动 探测 ) ， 用 以 标识 该 服务 具备 处 理 SSE 的 特征 。 同 时 注册 了 发 布 一 订阅 
资源 类 AirSsePubSubResource 和 广播 资源 类 AirSseBroadcastResource， 见 关注 点 2。 


2 .发布 一 订阅 资源 类 


资源 类 AirSsePubSubResource 用 于 支持 发 布 一 订阅 模式 的 SSE， 实 现 了 发 布 一 订阅 模式 中 阐述 的 流程 ， 示 例 代 码 如 下 。 


ePath ("pubsub") // 
关注 点 1 
: 为 发 布 -订阅 模式 定义 资源 路 径 
Public class AirSsePubSubResource { 
private static EventOutput eventOutput = new EventOutput () 7 
@GET// 
关注 点 2 
: 提供 SSE 
事件 输出 通道 的 资源 方法 
@Produces (SseFeature .SERVER SENT EVENTS) 
public EventOutput publishMessage() throws IOException { 
return eventOutput; 


} 
@POST// 


关注 点 3 
: 执 务 逻 辑 和 写 入 SSE 
通道 的 资源 方法 
Public void saveMessage (String message) throws IOException { 
L0G.info ("post message=" + message); 
eventOutput .write (new OutboundEvent .Builder () 
.id(System.nanoTime () + "") 
.name ("post message") 
.data (String.class, message) .build()); 


} 


在 这 段 代 码 中 ， 资 源 地 址 定义 了 发 布 一 订阅 模式 的 资源 地 址 为 “pubsub” ， 见 关注 点 1。GET 方 法 用 于 公布 SSE 通 信 通 道 ，POST 方 法 用 于 处 理 业 务 和 写 入 SSE 事 件 ， 两 者 逻辑 上 是 先后 被 调用 的 关系 。 
publishMessage() 方 法 公布 了 推送 事件 输出 通道 的 接口 ， 返 回 值 是 前 面 讲述 的 EventOutput 类 型 的 推送 事件 输出 信道 ， 见 关注 点 2。POST 方 法 saveMessage() 用 于 接收 客户 端 提交 的 信息 ， 并 将 其 写 入 推送 
事件 输出 信道 ， 根 据 HTML5 的 SSE 规 范 ， 出 站 事件 OutboundEvent 的 数据 结构 包含 三 个 主要 信息 : id、name 和 data， 见 关注 点 3。 


回 


3. 发 布 一 订阅 测试 类 


SseBroadcaseTest 类 继承 了 第 7 章 讲述 的 Jersey 的 测试 框架 类 JerseyTest， 省 去 了 样板 测试 代码 ， 本 例 只 需 注册 SSsE 特 征 类 SseFeature 和 发 布 一 订阅 测试 类 AirSsePubSsubResource。 示 例 代码 如 下 。 


public class SsePubSubTest extends JerseyTest 1{ 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
@Test 
public void testEventSource () throws InterruptedException, URISyntaxException { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 

final CountDownLatch latch = new CountDownLatch (testCount); 加 

// 
关注 点 1 
: 创建 EventSource 
实例 

final EventSource eventSource = new EventSource (target () .path (ROOT PATH)) { 

private inti; 


@Override 
public void onEvent (InboundEvent inboundEvent) { 
Er 
于 
关注 点 2 
: SSE 
输入 信道 监听 逻辑 
LOG.info("Received: " + inboundEvent.getId() + ":" 
+ inboundEvent.getName () + ":" + new String (inboundEvent.getRawData()))7 


Assert .assertEquals (messagePrefix + i+tt+, 
inboundEvent .readData (String.class)); 
latch.countDown (); 
} catch (ProcessingException e) { 
e.printstackTrace () 7 
} 
] 7 
for (inti = 0; i<testCount; i++) { 
target () .path (ROOT_PATH) .request () .Post (Entity. text (messagePrefix + i)); 
} 


try { 
latch.await (); 
} finally { 


eventSource.close (); 
} 


在 这 段 代 码 中 ， 用 于 测试 发 布 一 订阅 模式 功能 和 流程 的 方法 testEventSource() 是 一 个 集成 测试 方法 ， 模 拟 了 客户 端 监听 并 处 理 SSE 事 件 的 流程 。 在 该 测试 方法 中 ， 首 先 创建 EventSource 实 例 ， 并 通过 
该 实例 请 求 服务 器 端 GET 方 法 以 获得 SSE 事 件 输出 信道 ， 见 关注 点 1。 在 EventSource 实 现 中 ，onEvent() 方 法 中 做 了 三 件 事 ; 第 一 是 打印 输出 服务 器 推送 事件 的 内 容 ， 内 容 包括 前 面 讲述 的 SSE 规 范 定义 的 数 
据 结构 : id、name 和 data; 第 二 是 使 用 相等 断言 测试 服务 器 端 返 回 数据 是 否 符合 预期 } 第 三 是 调用 同步 器 CountDownLatch 实 例 的 countDown() 方 法 (原因 见 下 文 ) ， 见 关注 点 2。 


测试 代码 中 使 用 CountDownLatch 的 原因 是 在 测试 流程 中 ， 通 过 GET 订 阅 服务 器 SSE 事 件 通知 和 通过 POST 发 送 数 据 两 个 异步 操作 ， 而 我 们 期 待 的 顺序 是 在 执行 完 POST 代 码 块 后 ， 前 面 代码 块 中 定义 的 
监听 和 处 理 推送 事件 的 onEvent() 方 法 才 被 执行 ， 即 前 者 先 被 执行 但 前 者 的 回调 后 被 触发 。 为 此 ， 如 8.2.1 节 所 述 ， 测 试 流 程 在 POST 代码 块 后 ， 调 用 了 CountDownLatch 实 例 的 await( 方 法 ， 使 得 测试 主线 
程 被 阻塞 而 不 是 执行 完 ， 以 便 等 待 回调 被 执行 。 所 以 ，onEvent() 方 法 的 第 三 步 是 调用 CountDownLatch 实 例 的 countDown() 方 法 来 递减 其 内 部 计数 器 ， 确 保 主线 程 最 终 被 唤醒 。 


4 .广播 资源 类 
资源 类 AirSseBroadcastResource 用 于 支持 广播 模式 的 SSE， 示 例 代码 如 下 。 


@Path ("broadcast")// 


关注 点 1 
: 模式 定义 资源 路 径 
public class AirSseBroadcastResource { 
private static final BlockingQueue<BroadcastProcess>processQueue = 
new LinkedBlockingQueue<> (1)，; 
@Path ("book") 
@POST 
public Boolean PostBook (@DefaultValue ("0") QQueryParam("total") int total, 
String bookName) { 


// 
关注 点 2 
: 调用 BroadcastProcess 
实例 实现 广播 
final BroadcastProcess broadcastProcess = new BroadcastProcess (total, bookName); 
processQueue.add (broadcastProcess); 
Executors.newSingleThreadExecutor () .execute (broadcastProcess); 
return true; 


} 


i 
关注 点 3 
: 广播 处 理 线程 类 
static class BroadcastProcess implements Runnable { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
public void run() { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
OutboundEvent .Builder eventBuilder = new OutboundEvent .Builder () 
.mediaType (MediaType.TEXT PLAIN TYPE); 
OutboundPvent event = eventBuilder.id(processId + "") 
.name ("New Book Name") 
.data (String.class, bookName) .build(); 
broadcaster .broadcast (event) 7 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代 码 中 ， 资 源 地 址 定义 了 广播 模式 的 资源 地 址 为 “broadcast” ， 见 关注 点 1。 实 现 广播 的 核心 代码 块 位 于 内 部 线程 类 BroadcastProcess 中 ， 该 线程 类 使 有 
广播 出 去 ， 见 关注 点 3。 


POST 方法 postBook() 资 源 地 址 是 broadcast/book 


于 接收 客户 端 提交 的 收听 广播 的 客户 端 数量 和 最 新 图 书 
缓存 到 BlockingQueue 实 例 中 。 如 8.2.1 节 所 述 ，BlockingQueue 的 add() 方 法 会 在 尝试 入 队 失 败 时 ， 直 接 抛 出 异常 ， 意 味 着 广播 类 只 缓存 最 新 的 一 条 医 
程 阻塞 / 挂 起 ， 见 关注 点 2。 缓 存 队 列 会 被 GET 方 法 消费 ， 由 于 篇 幅 所 限 ， 因 此 没有 展示 全 部 代码 ， 读 者 可 以 从 源 代码 中 查阅 。 


广播 类 SseBroadcaster 实 例 将 SSE 事 件 


言 息 。 EE 


下 


接收 数据 ， 该 方法 会 动态 生成 一 个 线程 类 BroadcastProcess 的 实例 ， 并 尝试 将 其 
书 资源 信息 ， 直 接 失败 的 处 理 可 以 避免 客户 端 请 求 线 


广播 测试 类 SseBroadcaseTest 与 前 一 测试 非常 类 似 ， 不 再 讲述 相同 部 分 。 需 要 额外 说 明 的 是 ， 在 每 一 个 客户 端的 GET 请 求 中 ， 生 成 EventSource 类 实例 的 过 程 是 通过 EventSource 类 的 内 部 Builder 完 成 


的 ， 并 没有 自动 打开 SSE 信 道 ， 


5. 集 成 测试 


集成 测试 更 为 普遍 的 方式 是 使 


(1) 测试 发 布 一 订阅 


启动 示例 服务 ， 然 后 使 


因此 在 注册 监听 、 覆 盖 onEvent0) 方 法 后 ， 显 式 调 | 


cURL 命令 直接 对 资源 地 址 进行 访问 ， 即 时 检测 资源 方法 的 功能 ,或 者 使 


两 个 终端 /控制 台 沉 


试 发 布 一 订阅 流程 。 


open() 方 法 ， 读 者 可 在 源 代码 中 查阅 相关 内 容 。 


Shell 脚 本 编写 cURL 请 求 。 本 例 将 使 


cURL 命令 分 别 对 上 述 的 两 种 模式 的 实现 进行 集成 测试 。 


在 第 一 个 终端 中 输入 如 下 cURL 命令 ， 然 后 等 待 其 输出 。 这 一 步 请 求 了 GET 方 法 并 建立 了 HTTP 连 接 。 


QL < 


“Accept: text/event-stream" -~-url http://localhost:8080/sse/event/pubsub 


在 第 二 个 


Curl -X POST --data 
Curl -X POST --data 
Curl -X POST --data 
Curl -X POST --data 


"Javal.6" 


终端 中 依次 输入 如 下 cURL 命令 ， 以 模拟 多 次 提交 POST 请 求 的 流程 。 


"Javal.5" --url http://localhost:8080/sse/event/pubsub 
-url http://localhost:8080/sse/event/pubsub 
"Javal.7" --url http://localhost:8080/sse/event/pubsub 
"Javal.8" --url http://localhost:8080/sse/event/pubsub 


第 一 个 终端 应 输出 如 下 信息 ， 展 示 了 服务 器 端 在 处 理 每 一 次 POST 请 求 时 ， 向 导 


件 输出 通道 写 入 出 站 


event: post message 
id: 22127543063654 
data: Javal.5 
event: post message 
id: 22134553708520 
data: Javal.6 
event: post message 
id: 22141048454287 
data: Javal.7 
event: post message 
id: 22149255904866 
data: Javal.8 


(2) 测试 广播 


启动 服务 ， 然 后 根据 上 述 测试 场景 的 逻辑 ， 按 照 图 8-6 所 示 ， 使 


三 个 终端 /控制 台 测试 广播 流程 。 


Server 


BlockingQueue 


图 8-6 SSE 广 播 测试 示意 图 


在 图 8-6 所 示 的 第 一 终端 ClientA 中 输入 如 下 CURL 命 令 ， 其 中 ， 数 据 为 jax-rs2-guide， 参 数 total=2， 当 两 个 客户 端 连 接 到 服务 器 后 ， 向 全 部 客户 端 发 起 广播 。 


Curl -XK POST -data 


“jax-rs2-guide" http://localhost:8080/sse/event/broadcast/book?total=2 


接 下 来 ， 在 第 二 个 终端 ClientB 输 入 如 下 CURL 命 令 ， 终 端 会 出 现 阻塞 ， 不 去 管 它 ， 继 续 第 三 个 终端 ClientC 的 命令 输入 。 


CUrl =H 
“Accept: text/event-stream" http://localhost:8080/sse/event/broadcast/book?clientId=1 


在 第 三 个 终端 输入 如 下 cURL 命令 后 ,第 二 和 第 三 个 终端 会 同时 收 到 服务 器 的 广播 消息 。 


url = 及 
“Accept: text/event-stream" http://localhost:8080/sse/event/broadcast/book?clientId=2 


事件 消息 中 的 data 信 息 即 是 POST 提 交 的 内 容 。 


event: New Book Name 
id: 33035275182692 
data: jax-rs2-guide 


8.3 ”异步 通信 


JAX-RS 2.0 定 义 了 REST 的 异步 通信 API， 这 是 本 章 的 另外 一 个 主题 。REST 的 异步 通信 是 提高 REST 式 的 Web 服 务 的 性 能 、 执 行 效率 不 可 或 缺 的 技术 ， 同 时 异步 通信 可 以 增强 开发 过 程 中 业务 实现 的 功能 
性 和 灵活 性 。 本 章 前 述 的 服务 器 推送 技术 属于 异步 通信 的 一 种 场景 ， 即 服务 器 主动 向 客户 端 推送 数据 和 资源 状态 的 变化 。 此 外 ， 还 有 一 种 异步 通信 的 场景 是 当 客 户 端 提交 请 求 后 ， 服 务 器 通过 异步 的 方式 接 
收 并 处 理 请 求 ， 此 时 客户 端 线程 可 以 自由 选择 是 否 阻塞 线程 等 待 处 理 结果 。 该 场景 适用 于 处 理 信息 较 大 、 处 理 时 间 较 长 的 情况 ， 和 服务 器 推送 技术 既 有 相似 之 处 又 有 不 同 。 


在 JAX-RS 2.0 出 现 之 前 ，REST 的 异步 通信 实现 方式 并 没有 统一 的 标准 。 在 进入 JAX-RS 2.0 的 异步 规范 这 个 主题 之 前 ,我 们 先 来 简单 了 解 一 下 REST 应 用 中 都 出 现 了 哪些 异步 解决 方案 ， 从 而 在 宏观 上 掌握 
异步 通信 的 机 制 。 


© 阅读 指导 ”8.3 节 示例 所 在 目录 是 jax-rs2-guide\sample\8\asyn-rest。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/8/asyn-rest。 


1.Polling 异 步 通 信 


Polling 异 步 通信 方案 使 用 的 技术 结合 了 前 述 的 HATEOAS 和 Web Link， 以 及 Polling 技 术 ， 如 图 8-7 所 示 。 


服务 器 会 在 接收 请 求 后 立即 (以 HATEOAS 或 者 Web Link 技 术 ) 返回 给 客户 端 一 个 查询 处 理 结果 的 资源 地 址 ， 并 结束 这 一 次 的 请 求 一 响应 流程 ，HTTP 连 接 关 闭 ，HTTP 状 态 码 为 202 (注意 : 不 是 HTTP 
状态 200 OK，202 代 表 服 务 器 已 接收 请 求 但 尚未 处 理 ) 。 客 户 端 通过 轮 询 机 制 ， 向 新 的 REST 地 址 发 起 请 求 并 获得 该 处 理 的 进度 状态 (完成 状态 为 HTTP 状 态 码 100， 如 果 请 求 过 期 或 者 资源 地 址 错误 ， 则 
HTTP 状 态 码 为 404， 即 找 不 到 ) ， 并 最 终 在 获取 处 理 完毕 信息 后 结束 轮 询 。 


这 种 解决 方案 比 起 同步 处 理 的 优点 是 客户 端 可 以 即时 得 到 服务 器 的 反馈 ， 并 在 获得 最 终结 果 之 前 ， 有 机 会 处 理 后 续 业 务 。 另 外 ，Polling 技 术 不 需要 对 服务 器 和 客户 端 使 用 额外 的 第 三 方 支持 包 ， 易 于 实 
现 。 缺 点 在 前 面 关于 Polling 一 节 已 经 阐述 过 。 


2.Web Hook 异 步 通 信 


Web Hook 解 决 方案 是 指 在 客户 端 发 送 请 求 时 ， 将 一 个 回调 地 址 同时 发 送 给 服务 器 ， 服 务 器 接收 响应 后 ， 异 步 处 理 请 求 并 对 本 次 请 求 即刻 做 出 响应 ， 客 户 端 随即 处 理 其 他 业务 并 监听 回调 。 服 务 器 端 在 
响应 客户 端 后 ， 继 续 以 异步 的 方式 处 理 刚才 的 请 求 ， 在 处 理 完毕 后 ， 通 过 回调 地 址 通知 客户 端 处 理 结果 ， 如 图 8-8 所 示 。 
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图 8-7 客户 端 轮 询 实 现 异 步 通信 示意 
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8-8 ”Web Hook 实现 异步 通信 示意 图 


asynchronous 
handling 


Web Hook 解 决 方案 的 优点 是 覆盖 了 Polling 方 案 并 且 没 有 Polling 方 案 中 无 效 的 轮 询 负载 。 但 是 ， 这 种 方案 无 法 在 浏览 器 作为 客户 端的 场景 中 实施 ， 因 为 浏览 器 无 法 提供 一 个 回调 地 址 给 服务 器 。 因 此 ， 


该 方案 适用 于 另外 一 个 服务 器 作为 客户 端的 场景 。 另 外 ， 和 后 面 的 解决 方案 比 起 来 ， 该 方案 还 是 多 出 了 一 次 服务 器 回调 客户 端的 HTTP 连 接 。 


3.Comet 异 步 通信 


Comet 技 术 在 服务 器 推送 业务 中 的 处 理 流程 同样 适用 于 这 里 的 异步 通信 ， 客 户 端 发 送 请 求 后 ， 可 以 继续 执行 后 续 业 务 并 监听 服务 器 返回 的 处 理 结果 的 通知 ， 如 
步 通信 可 以 在 一 次 请 求 一 响应 的 模型 中 完成 。 缺 点 在 8.1 节 已 经 阐述 过 。 


图 8-9 所 示 。Comet 解 决 方案 的 优点 是 异 


olling) 


一 一 一 一 一 一 "Connection 0pen- 一 一 一 一 二 > 


Comet(Long-p 


一 

TD 
Wn 
人 
=y 
TD 

号 
CC 
Tm 
wn 


status=202 


| 人 
ee 

Accept | 

| !asynchronous 
| 1 handling 

| status=200 
一 一 

result ! 

| | 

一 一 一 一 一 -connection close i 

| | 

| I 


图 8-9 Comet 实 现 异 步 通信 示意 图 


4.HTML5 异 步 通信 


HTML5 包 含 SSE 和 Web Socket。SSE 用 于 服务 器 推送 事件 ， 但 并 不 仅 限 于 这 样 使 用 ， 上 文 的 相关 示例 中 已 经 展示 了 处 理 异 步 通信 的 能 力 。Web Socket 无 疑 非常 适用 于 当下 讨论 的 场景 。 由 于 JAX-RS 
2.0 和 Jersey 并 没有 相关 的 描述 ， 因 此 本 书 不 涉及 Web Socket 的 讲述 ， 如 果 读 者 有 兴趣 ， 那 么 可 以 参考 前 面 推荐 的 资料 ， 学 习 其 如 何 实现 。 


8.4”JAX-RS 2.0 实 现 异步 通信 


JAX-RS 2.0 的 异步 处 理 是 通过 两 个 线程 实现 的 ， 其 中 一 个 线程 用 于 处 理 客户 端的 请 求 ， 另 一 个 线程 是 为 此 次 请 求 新 生成 对 ， 用 于 处 理 具体 业务 。 在 后 一 个 线程 处 理 开始 前 ， 前 一 个 线程 可 以 响应 客户 端 
请 求 正在 执行 ， 然 后 进入 挂 起 状态 ， 保 持 连 接 。 后 一 个 线程 执行 完毕 后 ， 唤 醒 前 一 个 线程 。JAX-RS 2.0 的 异步 实现 过 程 中 ， 线 程 的 管理 是 由 容器 实现 的 ， 这 是 Java EE 7 中 JSR 236 规 范 定义 的 功能 ， 读 者 可 
以 参见 《Java EE 7 Essentials》 一 书 的 第 10 章 。 可 以 说 ，Java 和 领域 的 并 发 处 理 ，jJava SE 5.0 是 一 个 里 程 碑 ， 在 Java EE 中 与 之 对 应 的 就 是 7.0 版 本 了 。 在 容器 级 别 有 了 并 发 的 支持 ， 客 户 端 等 待 服务 器 的 响应 
就 可 以 由 一 个 Future 实 现 ， 感 觉 上 就 像 Java SE 开发 中 ， 等 待 同一 个 VM 的 另 一 个 线程 一 样 。 


了 解 了 JAX-RS 2.0 异 步 处 理 的 流程 后 ， 接 下 来 我 们 进入 实践 。 


8.4.1 ”服务 端 实现 


在 JAX-RS 的 服务 器 端 ， 实 现 异步 通信 和 包括 两 个 技术 点 ， 一 个 是 资源 方法 中 对 AsyncResponse 的 使 用 ， 另 一 个 是 对 异步 通信 的 CompletionCallback 和 TimeoutHandler 接 口 的 实现 ， 本 节 将 分 别 讲述 。 


1. 异 步 资源 类 


异步 资源 类 AsyncResource 定 义 了 资源 地 址 为 books， 根 资源 地 址 为 rest-async， 资 源 路 径 为 rest-async/books， 示 例 代码 如 下 。 


@Path ("books") 
public class AsyncResource { 
@POST 
QConsumes ( {MediaType.APPLICATION XML, MediaType.TEXT XML }) 


关注 点 1 
: 异步 资源 方法 需要 定义 GSuspended 
注解 和 AsyncResponse 
public void asyncBatchSave (@Suspended final AsyncResponse asyncResponse, 
final Books books) { 
configResponse (asyncResponse); 
final BatchRunner batchTask = new BatchRunner (books .getBookList ()); 
Future<String>bookIdsFuture = 
Executors .newSingleThreadExecutor () .submit (batchTask); 
String ids; 
try { 
ids = bookIdsFuture.get (); 
A 


关注 点 2 
: 请 求 响应 线程 被 唤醒 


asyncResponse.resume (ids); 

} catch (InterruptedException | ExecutionException e) { 
LOGGER .error (e.getMessage ()); 

} 


在 这 段 代 码 中 ，POST 方 法 asyncBatchSave() 用 于 处 理 批量 保存 业务 (模拟 一 个 耗 时 的 处 理 场景 ) 。 该 方法 包含 两 个 参数 ， 第 一 参数 是 异步 响应 类 AsyncResponse 的 实例 (习惯 上 ， 位 于 前 面 的 参数 是 
上 下 文 环境 变量 参数 ， 业 务 参数 置 后 ) ， 使 用 注解 @Suspended 来 标识 ， 见 关注 点 1。 在 执行 过 程 中 ， 请 求 处 理 线程 被 挂 起 ， 直 到 异步 请 求 处 理 结束 ， 异 步 响应 实例 的 resume() 方 法 被 调用 ， 请 求 处 理 线程 
才 被 唤醒 ， 将 resume() 方 法 的 参数 作为 返回 值 响 应 给 客户 端 ， 见 关注 点 2。 


2. 超 时 和 


回 


调 


JAX-RS 2.0 定 义 了 处 理 完成 回调 接口 CompletionCallback。 当 请 求 处 理 完成 时 ，CompletionCallback 的 实例 会 被 回调 。 实 现 onComplete() 方 法 可 以 监听 请 求 处 理 完成 事件 并 实现 相关 业务 流程 。 
CompletionCallback 的 实现 可 以 作为 AsyncResource 的 register() 方 法 的 参数 来 配置 ， 这 样 配置 后 ，AsyncResource 实 例会 在 resume() 被 调用 后 执行 回调 方法 onComplete0， 示 例 代码 如 下 。 


asyncResponse.register (new CompletionCallback() { 
QOverride 
Public void onComplete (Throwable throwable) { 
if (throwable == null) { 
LOGGER. info ("CompletionCallback-onComplete: OK"); 
} else { 
LOGGER. info ("CompletionCallback-onComplete: ERROR: " + throwable.getMessage()); 
} 


DD); 


JAX-RS 2.0 定 义 了 连接 断 开 回调 接口 ConnectionCallback。 当 请 求 一 响应 模型 的 连接 断 开 时 ，ConnectionCallback 的 实例 会 被 回调 。 实 现 onDisconnect() 方 法 可 以 监听 连接 断 开 事件 并 实现 相关 业 
务 ， 比 如 主动 唤醒 AsyncResource 实 例 并 设置 HTTP 状 态 码 为 410、 客 户 端 请 求 资源 不 可 用 (Response.Status.GONE) 来 完成 响应 。ConnectionCallback 的 实现 可 以 作为 AsyncResource 的 register() 方 法 
的 参数 来 配置 ， 示 例 代码 如 下 。 


asyncResponse.register (new ConnectionCallback() { 
QOverride 
public void onDisconnect (AsyncResponse disconnected) { 
disconnected.resume (Response.status (Response.Status .GONE) 
.entity("disconnect!") .build()); 
¢ 
Ds 


JAX-RS 2.0 定 义 了 超时 处 理 器 接口 TimeoutHandler 专 门 处 理 异步 响应 类 超时 ， 当 预期 的 超时 时 间 到 达 后 ，TimeoutHandler 的 实例 会 被 调用 。 实 现 handleTimeout() 方 法 可 以 监听 超时 事件 并 处 理 相关 
业务 ， 比 如 主动 唤醒 AsyncResource 实 例 并 设置 HTTP 状 态 码 为 503、 服 务 器 端 服务 不 可 用 (Response.Status.SERVICE_UNAVAILABLE) 来 完成 响应 。TimeoutHandler 的 实现 可 以 作为 AsyncResource 的 
setTimeoutHandler() 方 法 的 参数 来 配置 。AsyncResource 的 setTimeout() 方 法 用 于 设置 超时 时 间 ， 默 认 情况 下 AsyncResource 永 不 超时 。 示 例 代 码 如 下 。 


asyncResponse.setTimeoutHandler (new TimeoutHandler() { 
QOverride 
public void handleTimeout (AsyncResponse asyncResponse) { 
asyncResponse.resume (Response. status (Response.Status.SERVICE UNAVAILABLE) 
.entity ("Operation time out.") .build()); 
} 
DD); 
asyncResponse.setTimeout (TIMEOUT, TimeUnit.SECONDS); 


84.2 ”客户 端 实现 和 测试 


相应 的 ，JAX-RX 为 客户 端 提供 了 用 于 执行 异步 请 求 的 API。 开 发 者 使 用 这 样 的 方法 可 以 实现 对 服务 器 端 异 步 的 请 求 ， 同 时 也 可 以 使 用 客户 端的 异步 调用 实现 对 服务 器 端 异 步 通信 的 测试 。 


1. 异 步 测 试 类 
异步 测试 类 TIAsyncJFTTest 继 承 了 Jersey 测 试 框 架 类 JerseyTest， 异 步 测试 没有 额外 的 配置 ， 示 例 代码 如 下 。 


public class TIAsyncJFTTest extends JerseyTest { 

QTest 

Public void testAsyncBatchSave() throws InterruptedException, ExecutionException { 
List<Book>bookList = new ArrayList<> (COUNT); 
try { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
J 
关注 点 1 
G 求 方法 的 调用 使 用 AsyncInvoker 
实例 
final AsyncInvokerasync = request.async () 7 
final Future<String>responseFuture = async.post (booksEntity, String.class); 
String result = null; 
try { 
a 
关注 点 2 


: 异步 获取 服务 器 的 最 终 响应 
result = responseFuture.get (AsyncResource.TIMEOUT + 1, TimeUnit.SECONDS); 
} catch (TimeoutException e) { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 


在 这 段 代 码 中 ， 客 户 端 使 用 Asynclnvoker 接 口 的 post() 方 法 提交 蜡 步 请 求 ， 见 关注 点 1。 该 方法 返回 Future 接 口 的 实例 ， 客 户 端 线程 可 以 以 非 阻塞 的 方式 处 理 其 他 业务 流程 ， 然 后 调用 Future 的 get() 方 
法 获取 服务 器 处 理 结果 ， 见 关注 点 2。 


2. 异 步 回 调 


可 以 在 Asynclnvoker 接 口 的 post( 方 法 中 ， 定 义 一 个 InvocationCallback 接 口 的 实例 ， 实 现 REST 调 用 的 回调 处 理 ， 示 例 代码 如 下 。 


final Future<String>responseFuture = async.post (booksEntity, 
new InvocationCallback<string>() { 
QOverride 


dy 
关注 点 1 
: 服务 器 请 求 处 理 成 功 的 回调 
public void completed (String result) { 
LOGGER.debug ("On Completed: " + result); 
QOverride 


// 
关注 点 2 
: 服务 器 请 求 处 理 失败 的 回调 


Public void failed(Throwable throwable) { 


LOGGER.debug ("On Failed: " + throwable.getMessage () ) 7 


throwable.PrintStackTrace () 7 
String result = null; 
try { 
result = responseFuture.get (AsyncResource.TIMEOUT 


+ 1, TimeUnit .SECONDS); 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


于 监听 并 处 理 REST 调 


在 这 段 代 码 中 ，completed() 方 法 


3. 集 成 测试 


启动 示例 服务 ， 然 后 在 终端 /控制 台 输 入 如 下 cURL 命令 来 测试 REST 异 


于 监听 并 处 理 REST 调 


成 功 事件 ， 见 关注 点 1。failed() 方 法 


失败 村 


件 ， 见 关注 点 2。 


止 ， 


处 理 。 示 例 中 的 这 个 资源 方法 模拟 实现 了 一 个 耗 时 的 


图 


图 


书 处 理 过 程 ， 预 期 的 返回 值 为 两 个 


书 资源 的 1D。 


curl -X POST -H "Content-Type:application/xml" 


http://localhost:8080/asyn-rest/rest-async/books --data-binary "<books><bookList><book 
bookName="'jax-rs2-guide'/><book bookName="'jsf-richfaces4-guide'/></bookList></books>" 


63 64 
8.5 本章 小 结 
本 章 对 推送 和 异步 进行 了 讲述 。 其 中 前 半 部 分 的 两 节 分 别 讲述 了 REST 通 信 中 服务 器 推送 事件 的 4 种 技术 和 Jersey 对 服务 器 端 推 送 事 件 (SSE) 技术 的 支持 。 后 半 部 分 的 两 节 分 别 讲述 REST 的 异步 通信 的 4 


种 技术 和 JAX-RS 2.0 的 异步 请 求 处 理 实现 。 下 一 章 ， 我 们 开始 讲 


第 9 章 ”Jersey 1.x 迁 移 


Jersey 1.x 作 为 JAX-RS 的 参考 实现 ， 当 前 版 本 为 1.18 (可 参考 https://jersey.java.net/download.html) 。 相 信 有 相当 数量 的 开发 者 首先 接触 的 是 Jersey 1.x， 
JAX-RS 2.0 规 范 的 支持 ， 掌 握 从 Jersey 1.x 迁 移 到 Jersey 2.x 这 一 过 程 的 要 点 是 非常 必要 的 。 本 章 将 讲述 迁移 过 程 中 需要 注意 的 


9.1 ”变更 Maven 依 赖 定 义 


首先 需要 注意 的 是 ，Jersey 1.x 使 用 的 包 名 是 Java 开 发 者 亲切 和 熟识 的 com.sun， 而 Jersey 2.x 使 用 的 是 org.glassfish。 抛 
地 将 版 本 号 修改 即 可 ， 而 是 要 全 面 排查 com.sun 这 个 包 名 关键 字 是 否 被 org.glassfish 蔡 换 掉 。 


GlassFish 项 目 集 。 因 


除了 项 目 名 称 坐标 的 变更 ， 扩 


以 上 所 述 的 变更 包含 如 下 所 示 的 对 Jersey 1.x 的 依赖 定义 ， 


此 ， 在 迁移 项 目的 过 程 中 ， 依 赖 定义 不 是 简 和 


展 包 的 命名 也 发 生 了 变化 。Jersey 1.x 对 扩 


[es 


Jersey 1.x 到 Jersey 2.x 的 迁移 。 


项 。 


这 一 变化 的 商业 目的 ， 我 们 作为 开发 者 ， 从 2.x 自 


供 读者 参考 。 


展 包 的 命名 使 用 的 是 com.sun.jersey.contribs， 而 Jersey 2.x 使 用 的 是 org.glassfish.jersey.ext。 


此 无 论 Java EE 容器 版 本 的 升级 还 是 对 


的 命名 中 更 容易 获知 其 归 


珊 了 J 


<dependency> 
<groupId>com. sun.jersey</groupId> 
<artifactId>jersey-servlet</artifactId> 
</dependency> 
<dependency> 
<groupId>com. sun.jersey</groupId> 
<artifactId>jersey-client</artifactId> 
</dependency> 
<dependency> 
<groupId>com. sun.jersey.contribs</groupId> 
<artifactId>jersey-apache-client</artifactId> 
</dependency> 
<dependency> 
<groupId>com. sun.jersey.contribs</groupId> 
<artifactId>jersey-spring</artifactId> 
</dependency> 
<dependency> 


<groupId>com. sun.jersey.jersey-test-framework</groupId> 
<artifactId>jersey-test-framework-external</artifactId> 


</dependency> 

<dependency> 
<groupId>com.sun.jersey</groupId> 
<artifactId>jersey-json</artifactId> 

</dependency> 


9.2 ”客户 端 迁 移 


客户 端的 代码 部 分 迁移 点 比较 多 ， 这 是 


主要 (并 不 是 全 部 ) 的 迁移 包括 Client 接 口 、WebTarget 接 口 


9.2.1 Client 接口 迁移 


AI 


Client 接 口 是 JAX-RS 2.0 中 定义 的 。 在 Jersey 1.x 中 使 


因为 在 JAX-RS 中 没有 提供 可 以 遵循 的 标准 。Jersey 1.x 的 客户 端的 实现 没有 标准 依 和 
准 。 听 起 来 这 似乎 很 难 对 应 ， 但 要 说 明 的 是 ，Jersey 作 为 JAX-RS 的 参考 实现 ， 为 这 个 标准 规范 提供 了 反 向 的 参考 ， 在 JAX-RS 2.0 的 客 


和 QueryParam 三 个 部 分 。 


居 ， 自 行进 行 了 实现 ， 而 Jersey 2.x 遵 循 的 是 JAX-RS 2.0 才 引入 的 客户 端 接 


户 端 定义 中 ， 借 鉴 了 Jersey 1.x 的 AP1， 因 


pache 的 HTTP 客 户 端 来 实例 化 。 而 Jersey 2.x 中 使 


JAX-RS 2.0 定 义 的 ClientBuilder 来 实例 化 ， 示 例 代 码 如 下 。 


标 


此 代码 迁移 还 是 有 据 可 循 的 。 


//Jersey 1.x 


DefaultApacheHttpClientConfig config = new DefaultApacheHttpClientConfig(); 


client = ApacheHttpClient .create 
(config 


主流 

//Jersey 2.x 

ResourceConfig config=new ResourceConfig() 
client=ClientBuilder.newClient 

(config 


(1) 属性 设置 


客户 端 配置 在 Jersey 2.x 版 本 中 更 直接 ， 即 使 用 property() 方 法 。 而 Jersey 1.x 中 要 先 获取 features， 然 后 将 属性 的 键 值 对 赋 给 features， 示 例 代 码 如 下 。 


//Jersey 1.x 
config.getFeatures () .put 
(FeaturesAndProperties .FEATURE DISABLE XML SECURITY, true 
); 
//Jersey 2.x 
config.property 
(MessageProperties.XML SECURITY DISABLE, Boolean.TRUE 
| 


(2) 设置 超时 


Jersey 2.x 使 用 ClientProperties 类 为 属性 键 定义 常量 ，Jersey 1.x 使 用 的 是 配置 类 本 身 。 超 时 配置 分 为 连接 超时 和 读 取 超时 ， 前 者 用 于 控制 通信 建立 连接 的 时 间 ， 后 者 用 于 控制 请 求 一 响应 过 程 中 ， 数 据 
从 服务 器 端 下 行 到 客户 端的 时 间 ， 示 例 代 码 如 下 。 


//Jersey 1.x 
config.getProperties() .put 
(ClientConfig.PROPERTY CONNECT TIMEOUT, this.connectionTimeout 
); 
config.getProperties() .put 
(ClientConfig. PROPERTY READ TIMFEOUT, this.readTimeout 


//Jersey 2.x 
config.property 
(ClientProperties.CONNECT TIMEOUT, this.connectionTimeout 
); 
config.property 
(ClientProperties. READ TIMEOUT, this.readTimeout 
) 7 


(3) 配置 代理 服务 器 


Jersey 2.x 的 代理 服务 器 的 配置 在 2.5 版 本 之 前 依然 需要 依赖 Apache 的 HTTP 客 户 端 。 这 种 配置 在 Jersey 2.5 版 本 中 已 经 去 掉 ， 以 实现 其 配置 的 完整 性 ， 使 Jersey 默 认 的 客户 端 (Jersey 客 户 端的 代理 还 可 
以 在 Apache 连 接 器 中 设置 ) 功能 更 趋 完 善 ， 迁 移 示 例 代 码 如 下 。 


//Jersey 1.x 
config.getProperties () .put 
(ApacheHttpClientConfig.PROPERTY PROXY URI, proxyUrl 
) 7 本 

//Jersey 2.5- 

config.property 

(ApacheHttpClientConfig.PROXY URI, proxyUrl 

); 

//Jersey 2.5+ 

config.property 

(ClientConfig.PROXY URI, proxyUrl 


9.2.2 ”WebTarget 接 口 迁移 


WebTarget 这 个 概念 是 在 JAX-RS 2.0 提 出 的 ， 在 Jersey 1.x 中 对 应 的 是 WebResource。 两 者 的 功能 类 似 ， 实 例 化 的 实现 上 区 别 不 是 很 大 。 两 者 的 主要 区 别 只 是 名 字 ， 显 然 规 范 中 的 名 字 更 容易 理解 其 仿 
而 Jersey 1.x 中 的 容易 和 资源 类 混淆 。 因 此 ， 这 部 分 的 迁移 比较 容易 。 迁 移 示例 代码 如 下 。 


< 


//Jersey 1.x 
WebResource createWebResource 
(final String url, final String username, final String password 
) throws HttpConnectionException { 
final Client client = createClient 
(true 
) 7 
client.adgdFilter 
(new HTTPBasicAuthFilter 
(username, password 
)); 
final WebResource webResource = client.resource 
(Curl 
return webResource; 


} 
//Jersey 2.x 
WebTarget createWebResource 
(final String url, final String username, final String password 
) throws HttpConnectionException { 
final Client client =createClient 
(true 
内 这 
WebTarget target=client.target 
UL 
) 
target .register 
(new HttpBasicAuthFilter 
(username, password 
让 
return target; 


} 


JAX-RS 2.0 规 定 了 请 求 中 媒体 类 型 定义 的 方法 名 称 为 request， 在 Jersey 1.x 中 对 应 的 是 accept() 方 法 。 另 外 ， 写 操作 在 JAX-RS 2.0 一 律 接 收 Entity 类 实例 ， 这 在 Jersey 1.x 中 没有 规定 。 迁 移 示例 代码 如 


//Jersey 1.x 

result = webResource.accept (MediaType.APPLICATION XML) .get (this.returnClass); 

result = webResource.accept (MediaType.APPLICATION XML) .Post (this.returnClass, postXml); 
//Jersey 2.x 

result = webTarget.request (MediaType.APPLICATION XML) .get (this.returnClass); 
Entity<String> postXmlEntity=Entity.entity (postXml,MediaType.APPLICATION XML); 

result = webResource.request (MediaType.APPLICATION XML) 

.Post (postXmlEntity, this.returnClass); 


9.2.3 QueryParam 


JAX-RS 2.0 为 WebTarget 定 义 了 queryParam() 来 设置 查询 条 件 键 值 对 。 在 Jersey 1.x 中 使 用 的 是 键 值 对 Map。 迁 移 示 例 代 码 如 下 。 


//Jersey 1.x 


final MultivaluedMap<String, String> queryParams 
queryParams .add ("start", indexStart); 
queryParams .add ("pagesize", pageSize); 


= new MultivaluedMapImpl (); 


final WebResource webResourceWithParameters = webResource.queryParams (queryParams); 


//Jersey 2.x 


WebTarget queryWebTarget =queryTarget .queryParam("start", indexStart); 
queryWebTarget=queryWebTarget .queryParam("pagesize", pageSize); 


需要 注意 的 是 ，WebTarget 的 链 式 赋值 并 不 改变 其 本 身 ， 这 在 5.1 节 的 讲述 中 已 经 说 明 。 因 此 ， 在 循环 代码 块 中 不 能 像 Jersey 1.x 为 键 值 对 Map 赋 值 那样 使 用 ， 而 应 当 接 收 每 次 赋值 的 结果 作为 下 一 次 赋 


值 的 句柄 。 迁 移 示例 代码 如 下 。 


//Jersey 1.x 


for (final GenericQueryParameter param : parameters) { 
queryParams .add (param.getParameterName (), param.getParameterValue ()); 


webResourceWithParameters = webResource.queryParams (queryParams); 


//Jersey 2.x 


for (final GenericQueryParameter param : parameters) { 
queryWebTarget = queryWebTarget .queryParam (param.getParameterName (), 


Param.getParameterValue ()); 


} 


9.3 ”服务 器 端 迁 移 


在 服务 器 端 ， 代 码 部 分 的 迁移 点 并 不 是 很 多 。 配 置 上 ，web.xml 文 件 中 定义 的 Servlet 名 称 ， 需 要 修改 为 相应 的 包 名 和 配置 项 名 称 ， 这 在 第 2 章 的 示例 中 已 经 详 述 。 关 于 配置 部 分 可 参考 第 10 章 。 需 要 注 


意 的 是 ，Jersey 2.0 引 入 了 HK2 作 为 依赖 注入 框架 。 但 是 ， 实 际 的 项 目 中 更 多 的 是 和 Spring 集成 ， 因 此 下 | 


由 于 Jersey 1.x 集 成 Spring 的 最 高 版 本 是 Spring 2.6.5， 


回 


简 述 在 迁移 中 集成 Spring 的 变化 。 


对 比 配置 的 示例 代码 如 下 。 


因此 无 法 使 用 Spring 3.x 的 特性 。Jersey 2.x 引 入 Spring 3.x 作 为 集成 版 本 ， 


//Jersey 1.x 
<servlet> 


<servlet-name>Jersey Spring Web Application</servlet-name> 
<servlet-class>com. sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class> 


<init-param> 


<param-name>com. sun.jersey.config. feature.DisableXxmlSecurity</param-name> 


<param-value>true</param-value> 
</init-param> 


<init-param> <param-name>com.sun.jersey.config. 


<param-value>false</param-value> 
</init-param> 
</servlet> 
<servlet-mapping> 


feature.1logging.DisableEntitylogging</param-name> 


<servlet-name>Jersey Spring Web Application</servlet-name> 


<url-pattern>/*</url-pattern> 
</servlet-mapping> 
//Jersey 2.x 
<?xml version="1.0" encoding="UTF-8"?> 


<web-app xmlns="http://java.sun.com/xml/ns/Java EE" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance™ 
xsi:schemaLocation="http://java.sun.com/xml/ns/Java EE http://java.sun.com/xml/ns/Java EE/web-app_3_0.xsd" 


version="3.0"> 
<display-name>simple-service</display-name> 
<listener> 


<listener-class>org.springframework.web.context .ContextLoaderListener</listener-class> 


</listener> 
<context-param> 


<param-name>contextConfigLocation</param-name> 
<param-value>classpath:applicationContext .xml</param-value> 


</context-param> 
</web-app> 


本 章 没有 讲述 Jersey 2.x 小 版 本 之 间 的 迁移 ， 因 为 在 Jersey 快 速 的 发 展 中 ， 其 内 部 API 在 不 断 优化 中 ， 详 见 https://jerseyjava.net/documentation/latest/user-guide.html#migration。 本 书 的 示例 代 
码 会 根据 最 新 版 本 的 API 进 行 调整 ， 并 在 GitHub 上 作为 分 支 提供 给 读者 。 


9.4 本章 小 结 


本 章 讲述 了 Jersey 1.x 迁 移 到 Jersey 2.x 的 细节 ， 这 些 内 容 来 自 笔者 的 实际 工作 经 验 。9.1 节 列举 了 依赖 包 的 变化 ，9.2 节 对 REST 客 户 端 接口 的 变化 进行 了 阐述 并 给 出 了 实例 ，9.3 节 简 述 了 服务 器 端的 变 


化 。 下 一 章 ， 我 们 开始 讲述 JAX-RS 的 调 优 内 容 。 


第 10 章 ”JAX-RS 调 优 


基于 JAX-RS 的 项 目 是 部 署 在 Servlet 容 器 或 者 Java EE 容 器 的 Web 服 务 ， 因 此 要 提高 这 类 项 目的 性 能 ， 除 了 在 编码 阶段 需要 注意 代码 的 质量 ， 在 配置 部 署 阶段 还 要 关注 网 络 负载 、Jersey 参 数 配置 以 及 对 
Java 虚 拟 机 调 优 ， 在 运行 阶段 还 要 对 运行 平台 的 操作 系统 、 服 务 器 软件 进行 监控 和 调 优 。 本 章 将 讲述 如 何 为 基于 JAX-RS 的 项 目 进行 调 优 。 


全 阅读 指南 第 10 章 示例 所 在 目录 是 jax-rs2-guide\sample\10\simple-service10。 


源 代码 地 址 : https://github.com/feuyeux/jax-rs2-guide/tree/master/sample/10/simple-service10。 


10.1 ”使 用 缓存 优化 负载 


系统 的 网 络 吞吐 能 力 是 其 性 能 的 重要 指标 ， 我 们 可 以 使 
和 缓存 是 降低 系统 和 网 络 负载 的 手段 之 一 。 本 节 将 讲述 基于 


10.1.1 缓存 协商 


操作 系统 自 带 的 工具 进行 监控 。 但 是 ， 监 控 只 能 判断 网 络 的 负载 情况 ， 而 降低 网 络 负载 是 提高 网 络 吞 吐 能 力 的 一 个 有 效 的 手段 。 使 用 动静 分 离 


AX-RS 的 项 目的 缓存 实践 。 


Jersey 支 持 使 用 通用 的 HTTP 头 进行 缓存 协商 。 在 HTTP 头 字段 中 ，Expires、Cache-Control 和 Last-Modified 作 为 缓存 过 期 时 间 的 判断 依据 。ETag 用 于 标识 一 次 请 求 。If-Modified-Since 和 If-None- 


Match 是 缓存 控制 的 两 种 处 理 标识 。 下 面 分 别 讲 述 它们 的 使 用 。 


1) Expires: 用 于 记录 HTTP 缓 存 过 期 时 间 头 信息 。Expires 简 单 易 用 ， 服 务 器 据 此 判断 请 求 是 否 应 该 刷新 。 但 是 Expires 的 标识 比较 粗糙 ， 其 缺点 是 当 服务 器 的 时 区 和 本 地 时 间 与 客户 端 上 的 不 一 致 时 ， 
会 影响 缓存 的 准确 性 。 


2) Cache-Control: 用 于 控制 HTTP 缓 存 属性 的 头 信息 。 常 用 的 属性 包括 : 


“ Public: 响应 可 缓存 在 任何 缓存 区 ; 

“ Private: 响应 只 能 缓存 在 私有 缓存 区 ， 不 能 被 共享 缓存 处 理 ; 

: no-cache: 响应 不 能 缓存 (HTTP/1.0 用 Pragma 的 no-cache 替 换 ) ; 

* max-age: 缓存 最 大 时 间 (以 秒 为 单位 ) 。 和 Expires 共 存 时 ， 优 先 使 用 max-age。 和 Expires 对 比 ，max-age 使 用 的 是 相对 时 间 ， 因 此 不 存在 Expries 的 问题 。 
3) Last-Modified: 页 面 文件 最 后 的 修改 时 间 ， 精 确 到 秒 。 


4) If-Modified-Since: 是 指 自 从 某 个 时 间 点 开始 服务 器 提供 了 最 新 数据 。 当 服务 器 从 客户 端的 请 求 中 读 出 这 个 标识 后 ， 结 合 Cache-Control 中 定义 的 缓存 参数 ， 判 断 是 否 需要 刷新 数据 来 响应 当前 请 
求 。 如 图 10-1 所 示 ， 客 户 端 请 求 一 个 REST 资 源 ， 服 务 器 返回 最 新 数据 并 指定 Cache-Control 的 max-age 为 1200 秒 ，Last-Modified 为 当前 时 间 。 之 后 客户 端 再 次 发 起 对 该 资源 的 请 求 ， 服 务 器 根据 Cache- 
Control 的 max-age 和 Last-Modified 计 算是 否 需要 刷新 数据 。 如 果 需 要 ， 即 执行 业务 处 理 并 返回 最 新 的 数据 ，HTTP 状 态 码 为 200 OK; 否则 直接 返回 缓存 数据 ，HTTP 状 态 码 为 304 Not Modified。 


ClientBrowser 


http:/Mocalhost:8080/simple-service10/webapilrestlast_modified?userld=eric 


Cache-Control —no-transform, max-age=1200 
Last-modified 


I-Modified-Since 


304 Not Modified 


10-1 IfModified-Since 流 程 示意 


5) ETag: 服务 器 端的 散 列 值 ， 每 次 请 求 处 理 都 是 唯一 的 。 


6) If-None-Match: 是 指 请 求 的 ETag 是 否 匹 配 。 如 图 10-2 所 示 ， 当 服务 器 从 客户 端的 请 求 中 读 出 这 个 标识 后 ， 会 与 当前 ETag 对 比 ， 如 果 符 合 ， 即 返回 缓存 数据 ，HTTP 状 态 码 为 304 Not Modified; 
否则 返回 最 新 数据 ，HTTP 状 态 码 为 200 OK。 


Client/Browser 


http://localhost:8080/simple-service 10/webapi/lrest/e_tag 


Cache-Control 一 no-transform, max-age=1200 
ETag 


If-None-Match 


304 Not Modified 


图 10-2 IfNone-Match 流 程 示意 图 


10.1.2 条 件 GET 


条 件 GET 是 使 f-Modified-Since 或 者 If-None-Match 头 信息 对 GET 请 求 进行 缓存 处 理 的 一 种 方案 。 本 节 使 用 本 章 提 供 的 示例 项 目 演示 如 何 实现 对 条 件 GET 方 法 的 支持 。 


(1) Last-Modified 


使 用 Chrome 浏 览 器 的 Postman 揪 件 向 支持 If-Modified-Since 条 件 GET 请 求 的 REST 资 源 发 起 请 求 ， 地 址 为 : http://localhost:8080/simple-service10/webapi/rest/last_modified， 如 图 10-3 所 示 。 


如 图 10-3 所 示 ， 返 回头 信息 有 6 个 字段 ， 包 含 Cache-Control 和 Last-Modified 信 息 ， 同 时 HTTP 状 态 码 为 200 OK。 


(2) IEModified-Since 


接 下 来 ， 在 请 求 头 信息 中 携带 If-Modified-Since 信 息 ， 内 容 为 服务 器 返回 的 Last-Modified 值 。 立 即 再 次 向 同一 地 址 发 出 请 求 ， 如 图 10-4 所 示 。 


如 图 10-4 所 示 ， 服 务 器 响应 的 HTTP 状 态 码 是 304 Not Modified， 因 为 最 后 修改 时 间 与 服务 器 当前 时 间 之 差 没 有 达到 最 大 缓存 的 时 间 1200 秒 ， 因 此 直接 返回 缓存 数据 。 


(3) ETag 


使 用 Chrome 浏 览 器 的 Postman 插 件 向 支持 If-None-Match 条 件 GET 请 求 的 REST 资 源 发 起 请 求 ， 地 址 为 : http://localhost:8080/simple-service10/webapi/rest/e_tag， 如 图 10-5 所 示 。 


如 图 10-5 所 示 ， 返 回头 信息 有 6 个 字段 ， 包 含 Cache-Control 和 ETag 信 息 ， 同 时 HTTP 状 态 码 为 200 OK。 


(4) IENone-Match 


接 下 来 ， 在 请 求 头 信息 中 携带 ff-None-Match 信 息 ， 内 容 为 服务 器 返回 的 ETag 值 。 立 即 再 次 向 同一 地 址 发 出 请 求 ， 如 图 10-6 所 示 。 


hitpiiocalhost:8080/simple-semvicelOiwebaplirestlast _ modified?userld=eric | 


Userld eric 


URL Parameter Key Value 


Header 


Preview Add to collection 


Headers (6) STATUS 200 Ok [RD 53 ms 


Cache-Control3 no-transtorm, max-age=1l200 
Content-Length 二 了 
Canmtent-TYBEe text/plain 


Date3 Sun, 17 NOVw 201306:52:32 GMT 


Last-Modified 2 Sun, 17 Now 201306:52:32 GMT 


SErvers Apache-Coyotei,1 


图 10-3 ”响应 头 字 段 Last-Modified 


http://localhost-8080/simple-service10/webapi/rest/last modiffed?userld=eric 


USerld eric 


URL Parameter Key Value 


lf-Modified-Since Sun, 17 Nov 2013 06:53:30 GMT 


Header Value 


Preview Add to collection 


Headers (3) EELS 304 Not Modified | 1 局 60 ms 


Cache-Control3 no-transform, max-age=1200 


Date 3 Sun,17 Nov 2013 06:53:42 GMT 


Server3 Apache-Coyote/1.1 


图 10-4 ”请 求 头 字段 IfModified-Since 


http-//localhost:8080/simple-service1i0/webapi/rest/e tag?userld=eric 


USerld eric 


URL Parameter Key Value 


Preview Add to collection 


Headers (6) ET 200OK MI! 172 ms 


Cache-Control> no-transform, max-age=1200 


Content-Length > 4889 
Content-Type > text/plain 
Date > Sun,17 Nov 2013 08:29:03 GMT 


ETag > "3121799" 


Server> Apache-Coyote/1.1 


图 10-5 ”响应 头 字段 ETag 


http-/localhost-8080/simple-service10Mwebapiirestie tag?userld=eric 


USerld 


Preview Add to collection 


Headers (4) I 304 Not Modified | 个 73 ms 


Cache-Control3 mo-transform max-age=1200 
Date 3 Sun, 17 Nov 201308:31:30GMT 
Elag3 "3121799" 


Serverz Apache-Coyote/l.1 


10-6 ”请 求 头 字 段 If-None-Match 


如 图 10-6 所 示 ， 服 务 器 响应 的 HTTP 状 态 码 是 304 Not Modified， 因 为 最 后 修改 时 间 与 服务 器 当前 时 间 之 差 没有 达到 最 大 缓存 的 时 间 1200 秒 ， 因 此 直接 返回 缓存 数据 。 


通过 上 述 的 实验 ， 我 们 从 浏览 器 端 了 解 了 HTTP 条 件 GET 的 原理 及 其 在 REST 服 务 中 的 实践 。 接 下 来 ， 我 们 走 进 服务 器 端 ， 讲 述 REsT 缓 存 的 代码 实现 。 


10.1.3 “REST 缓 存 实 践 


Jersey 提 供 了 对 条 件 GET 支 持 的 方法 ， 本 节 将 从 实践 角度 进行 讲述 。 
(1) CacheControl 


JAX-Rs 提 供 了 CacheControl 类 与 上 述 的 HTTP 头 信息 Cache-Control 对 应 。 在 REST 请 求 处 理 的 方法 中 ， 可 以 通过 构造 CacheControl 实 例 ， 并 为 其 设置 参数 值 ， 使 其 作为 HTTP 响 应 头 信息 中 的 Cache- 
Control 信 息 ， 示 例 代 码 如 下 。 


CacheControl cacheControl = new CacheControl (); 
CacheControl .setMaxAge (1200) ， 
cacheControl .setMustRevalidate (true); 


在 这 段 代 码 中 ，Cache-Control 信 息 包含 了 max-age 和 must-revalidate， 分 别 设置 为 20 分 钟 (1200 秒 ) 和 强制 客户 端 不 缓存 数据 。 


(2) EntityTag 


JAX-RS 提 供 了 EntityTag 类 与 上 述 的 HTTP 头 信息 ETag 对 应 。EntityTag 实 例 用 来 设置 HTTP 头 信息 ETag， 示 例 代码 如 下 。 


EntityTag tag = new EntityTag (userId.hashCode() + 
SN 7 


在 这 段 代 码 中 ， 使 用 当前 用 户 ID 的 hashcode 作 为 ETage 的 值 。 


(3) ResponseBuilder 


在 完成 HTTP 头 信息 的 设置 后 ， 可 以 填充 给 Response 实 例 ， 作 为 响应 头 信息 ， 示 例 代 码 如 下 。 


Response.ok (getIt () ) .cacheControl (cacheControl) .build() 
Response.ok (getIt () ) .cacheControl (cacheControl) .lastModified (date) .build(); 
Response.ok (getIt () ) .cacheControl (cacheControl) .tag (tag) .build() 


在 这 段 代 码 中 ， 静 态 方法 Response.ok() 的 返回 类 型 是 ResponseBuilder， 通 过 使 用 ResponseBuilder 可 以 为 Response 实 例 填 充 HTTP 头 信息 。 本 例 示范 了 不 同 HTTP 头 信息 的 填充 ， 分 别 是 Cache- 


Control 信 息 、Last-Modified 信 息 和 ETag 信 息 。 


(4) evaluatePreconditions0 方法 


Jersey 对 If-Modified-Since 和 If-None-Match 的 支持 是 通过 Request 接 口 的 evaluate-Preconditions() 方 法 实现 的 。 


If-Modified-Since 的 实现 是 传 入 Date 类 型 的 实例 ， 代 表 最 后 修改 时 间 ， 输 出 是 ResponseBuilder 实 例 ， 如 果 不 为 空 ， 即 代表 缓存 尚未 失效 ， 否 则 重新 获取 数据 并 构造 Cache-Control 和 lastModified 响 


应 头 信息 ， 示 例 代码 如 下 。 


Date lastModified = map.get (userId); 
Response.ResponseBuilder rb = null; 
if (lastModified != null) { 
rb = request .evaluatePreconditions (lastModified); 
} 
if (rb != null) { 
return rb.cacheControl (cacheControl) .build(); 
else { 
Date date = new Date(); 
map.put (userId, date); 
return Response.ok (getIt () ) .cacheControl (cacheControl) .lastModified (date) .build(); 


If-None-Match 的 实现 是 传 入 EntityTag 实 例 ， 代 表 当前 ETag 值 ， 输 出 是 ResponseBuilder 实 例 ， 如 果 不 为 空 ， 即 代表 缓存 尚未 失效 ， 否 则 重新 获取 数据 并 构造 Cache-Control 和 ETag 响 应 头 信息 ， 示 


例 代 码 如 下 。 


EntityTag tag = new EntityTag (userId.hashCode() + ""); 
rb = request.evaluatePreconditions (tag); 
if (rb != null) { 
return rb.cacheControl (cacheControl) .build(); 
} else { 
return Response.ok (getIt () ) .cacheControl (cacheControl) .tag (tag) .build(); 
} 


10. 


1.4 ”ab 测试 


ab 是 Apache 的 HTTP 服 务 器 benchmark 工 具 ， 可 以 对 条 件 GET 进 行 吞 吐 量 测试 。 使 用 ab 工具 模拟 100 个 客户 端 进行 1000 次 的 请 求 来 测试 资源 地 址 http://192.168.0.163:8080/simple- 


service10/webapi/rest， 测 试 报告 如 下 所 示 。 


//ab - Apache HTTP server benchmarking tool 


//ab [ -c concurrency ] [ -H custom-header ] [ -n requests ] [http[s]://]hostname[:port]/path 
ab -n1000 -c100 http://192.168.0.163:8080/simple-servicel0/webapi/rest 
Requests per second: 131.13 [#/sec] (mean) 


Time per request: 762.574 [ms] (mean) 

ab -n1000 -c100 -H 'If-Modifed-Since:"' 
http://192.168.0.163:8080/simple-servicel0/webapi/rest/last modified?userId=eric 
Requests per second: 158.23 [#/sec] (mean) 加 

Time Per request: 632.006 [ms] (mean) 


样 ， 


如 上 述 测试 报告 所 示 ，-n 参 数 表 示 请 求 数 ，-c 参 数 表示 并 发 客户 端 数 。 当 没有 使 用 缓存 策略 时 ，100 个 客户 端 进行 1000 次 请 求 得 到 的 每 秒 请 求 次 数 大 约 是 131 次 ， 每 个 请 求 的 处 理 时 间 是 762.574ms。 同 
测试 参数 对 支持 条 件 GET 的 资源 地 址 进行 测试 ， 得 到 的 每 秒 请 求 次 数 大 约 是 158 次 ， 每 个 请 求 的 处 理 时 间 是 632.006ms。 


10.2 ”使 用 版 本 号 优化 服务 


在 REST 服 务 的 资源 地 址 中 加 入 版 本 号 ， 可 以 在 REST 服 务 接口 升级 后 方便 地 实现 对 旧 接口 的 长 期 支持 。 但 是 否 应 该 在 REST 资 源 中 使 用 版 本 号 ，REST 领 域 的 声音 并 不 一 致 。 本 节 站 在 使 用 版 本 号 为 开发 和 


运 维 人 员 带 来 效率 提升 的 角度 ， 讲 述 REST 服 务 中 的 版 本 号 。 


10.2.1 何 时 使 用 版 本 号 


1. 网 


REST 的 版 本 号 (version) 并 不 是 必须 存在 的 ， 我 们 从 B/S 结 构 的 网 站 和 应 用 软件 两 个 应 用 场景 讨论 在 REST 服 务 中 何 时 该 使 用 版 本 号 信息 。 


站 


网 站 的 特点 是 “永远 处 于 Beta 版 ”， 发 版 是 开发 团队 和 运 维 团队 的 日 常 工作 。 因 此 ， 确 保 与 外 系统 之 间 的 Web 服 务 始终 有 效 是 网 站 灰 度 测试 不 可 或 缺 的 环节 。 如 果 我 们 的 Web 服 务 升级 ， 那 么 必须 在 上 


线 前 确保 外 系统 的 接 入 没有 问题 。 


题 。 


服务 。 


最 直接 的 办 法 就 是 提供 带 有 版 本 号 的 地 址 ， 在 上 线 新 版 本 时 通知 对 方 修改 其 Web 服 务 接 入 地 址 。 这 个 场景 下 ， 外 系统 如 果 接 入 旧版 本 地 址 ， 可 以 继续 使 用 旧版 本 功能 ， 省 去 了 因 升级 导致 的 不 兼容 问 
此 后 ， 外 系统 的 开发 人 员 可 以 视 情况 将 其 接口 方法 升级 到 新 版 本 ， 然 后 接 入 新 版 地 址 。 


如 果 对 方 由 于 某 种 原因 无 法 修改 接 入 地 址 ， 我 们 的 系统 应 该 保留 旧 的 资源 方法 并 提供 兼容 性 解决 方案 。 例 如 ， 通 过 在 访问 者 身份 信息 和 请 求 头 信息 中 额外 定义 的 版 本 信息 等 方式 ， 相 应 地 为 其 提供 新 版 


其 实 ， 在 REST 式 的 Web 服 务 中 使 用 版 本 号 并 不 是 必要 的 。 如 果 必 须 使 用 ， 笔 者 推荐 将 最 新 版 本 的 资源 地 址 和 无 版 本 号 的 资源 地 址 一 并 使 用 ， 这 样 做 的 好 处 是 ， 如 果 接 入 端 不 使 用 带 有 版 本 号 的 地 址 ， 那 


么 其 接 入 的 永远 是 最 新 版 本 的 资源 地 址 ， 而 无 须 因为 服务 端的 频繁 升级 带 来 无 谓 的 修改 。 


2. 应 


用 软件 


如 果 我 们 开发 的 REST 式 的 Web 服 务 是 企业 管理 平台 一 类 的 软件 ， 而 且 出 现 带 版 本 号 的 资源 地 址 ， 那 么 该 版 本 号 应 该 和 软件 版 本 匹配 ， 退 一 步 讲 ， 即 使 从 来 都 没有 被 修改 过 ，version 信 息 也 应 该 相应 地 
升级 。 其 实 ， 在 软件 中 使 用 版 本 号 的 必要 性 很 低 ， 维 护 版 本 的 价值 本 身 就 不 大 。 笔 者 经 历 过 一 个 对 版 本 号 依赖 很 强 的 产品 ， 该 产品 历经 多 年 开发 ， 有 多 个 小 版 本 ， 其 中 多 数 是 为 支持 不 同 的 客户 开发 的 ， 小 
版 本 之 间 缺 乏 共性 ， 因 此 在 Web 服 务 中 定义 了 版 本 号 。 在 这 个 例子 中 ， 版 本 号 的 确 有 存在 的 必要 ， 但 排除 历史 原因 ， 因 此 一 个 优秀 的 设计 是 可 以 减少 日 后 不 必要 的 维护 成 本 的 。 


10.2.2 ”如 何 使 用 版 本 号 


纵然 笔者 以 浅薄 的 认识 站 在 尽量 不 去 使 用 版 本 号 的 行列 ， 但 当 需 要 使 用 版 本 号 的 需求 摆 在 面前 时 ， 头 等 大 事 还 是 考虑 如 何在 REST 服 务 中 实现 版 本 号 。 


1. 资 源 定义 


REST 服 务 对 版 本 号 信息 的 支持 有 两 种 方式 ， 即 通过 资源 地 址 (URL) 或 者 HTTP 头 信息 来 实现 ， 下 面 分 别 讲述 这 两 种 实现 。 


(1) URL 


通过 资源 地 址 实现 的 方式 实现 REST 的 版 本 信息 ， 其 URL 形 式 如 下 所 示 。 
http:/ /localhost:8080/simple-service10/webapi/rest/v1.0 
http:/ /localhost:8080/simple-service10/webapi/rest/v2.0 


在 服务 的 URL 中 ， 版 本 号 信息 作为 资源 路 径 的 一 部 分 加 入 到 context 与 资源 名 称 之 间 。 上 面 定 义 了 1.0 版 本 和 2.0 版 本 。 相 应 的 资源 方法 的 实现 并 不 复杂 ， 只 需 额外 增加 一 个 @Path 注 解 ， 示 例 代码 如 下 。 


@GET 

@Path ("v2.0") 

@Produces (MediaType.TEXT PLAIN) 

public String getIt2() 全 

http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


对 应 的 测试 代码 分 别 测试 了 两 个 版 本 的 资源 地 址 的 可 用 性 ， 示 例 代 码 如 下 。 


Q@Test 

public void testVersion() { 
Response response =target ("rest") .path ("v1.0") .request () .get (); 
Link link =response.getLink ("currentVersion") ; 
System.out.println (link); 
Response response2 =target ("rest") .path ("v2.0") .request () .get (); 
String result =response2.readentity (String.class); 
System.out .Println (result); 


(2) HEAD 


通过 头 信息 支持 版 本 号 需要 在 HTTP 头 信息 (HEAD) 中 指定 一 个 特殊 的 属性 ， 本 示例 使 用 X-API-Version 作 为 版 本 信息 的 标识 ， 示 例 代 码 如 下 。 


@GET 
@Path ("head-version") 
Q@Produces (MediaType.TEXT_ PLAIN) 
public String getIt3(@Context final HttpHeaders headers) { 

String version = headers.getRequestHeaders () .get ("X-API-Version") .get (0); 

if (version.equals ("2")) 

return getIt2(); 

http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代 码 中 ， 资 源 方法 getlt30 首 先 从 请 求 头 信息 中 获取 X-API-Version 属 性 信息 ， 该 属性 值 代 表 请 求 的 REST 版 本 信息 。 


对 应 的 测试 代码 通过 定义 请 求 头 信息 中 的 X-API-Version 值 对 不 同 版 本 的 资源 地 址 进行 访问 ， 示 例 代码 如 下 。 


QTest 
public void testHeadVersion() { 
Response response =target ("rest") .path ("head-version") .request () 
.header ("X-API-Version", "2") .get (); 
String result =response.readEntity (String.class); 
System.out .Println (result); 
1 > GET http://localhost:9998/rest/head-version 
1 > X-API-Version: 2 


一 个 REST 服 务 经 历 长 期 的 开发 后 ， 也 许 需 要 对 早期 的 Web 服 务 资源 地 址 进行 去 化 〈 即 逐渐 淘汰 ) 。 在 正式 废弃 旧版 本 的 资源 地 址 之 前 ， 应 该 提供 相当 一 段 时 间 ， 比 如 间隔 几 个 版 本 的 兼容 性 支持 的 时 
间 ， 并 在 API 文 档 中 给 出 最 后 支持 时 间 ， 以 便 外 系统 或 客户 端 有 充分 的 升级 准备 时 间 。 一 种 友好 的 通知 版 本 变更 的 方式 是 通过 响应 头 Link， 将 新 版 本 的 资源 地 址 响应 给 客户 端 ， 示 例 代 码 如 下 。 


@GET 
@Path 
Le 
) 
@Produces 
(MediaType.TEXT PLAIN 
) 


public Response getIt1 
(Q@Context UriInfo uriInfo 


final UriBuilder ub = uriInfo.getAbsolutePathBuilder (); 
final URI uri = ub.replacePath 

("rest/v2.0" 

) .build()> 
return Response.accepted() .link 

(uri, "currentVersion™" 

) .build()> 

} 


在 这 段 代码 中 ， 响 应 信息 提供 了 link 信 息 ， 其 rel 定 义 为 currentVersion， 代 表 该 资源 的 当前 版 本 ，uri 的 值 是 当前 版 本 的 资源 地 址 。 


10.3 ”使 用 参数 配置 优化 服务 


Jersey 提 供 了 丰富 的 配置 参数 ， 用 于 为 REST 服 务 特定 的 需求 提供 定制 。 本 节 将 分 3 部 分 讲述 Jersey 的 配置 : 通用 部 分 、 服 务 器 端 、 客 户 端 。 


10.3.1 通用 配置 


Jersey 提 供 的 通用 配置 类 org.glassfish.jersey.CommonProperties 位 于 jersey-common 包 内 。 在 应 用 中 通过 修改 通用 配置 的 值 ， 可 以 改变 Jersey 服 务 器 端 和 客户 端 两 侧 的 默认 行为 。 例 如 ， 禁 用 不 必要 


的 自动 探测 功能 ， 以 提高 系统 的 整体 性 能 。 表 10-1 提 供 了 Jersey 通 用 配置 参数 参考 。 


表 10-1 Jersey 通用 配置 参数 列表 


常量 名 称 及 参数 名 称 说 明 
FEATURE _ AUTO_DISCOVERY DISABLE jersey. es 
ene 了 J | “全 局 禁用 自动 探测 特征 。 默 认 值 =false 
config.disableAutoDiscovery 
JSON_ PROCESSING FEATURE DISABLE jersey. 禁用 对 Json Processing ( JSR-353 ) 特征 的 支持 。 默 认 值 


config.disableJsonProcessing =false 

METAINF SERVICES LOOKUP DISABLE jersey. 禁用 自动 加 载 META-INF/services 目录 下 的 SPI。 默 认 
config.disableMetainfServicesLookup 值 =false 
i 禁用 对 MOXyJson 特征 的 支持 。 默 认 值 =false 
OUTBOUND CONTENT LENGTH BUFFER 设置 响应 实体 缓存 的 大 小 和 响应 头 Content-Length 的 值 。 默 
Jersey.config.contentLength.buffer 认 值 =8192 


在 REST 应 用 中 修改 通用 配置 类 org.glassfish.jersey.CommonProperties 的 值 非常 简单 ， 示 例 代码 如 下 。 


public class AirApplication extends ResourceConfig { 
public AirApplication() { 
property (CommonProperties .FEATURE AUTO DISCOVERY DISABLE,true); 
property (CommonProperties.JSON PROCESSING FEATURE DISABLE, true); 
property (CommonProperties .METAINF SERVICES LOOKUP DISABLE,true); 
property (CommonProperties.MOXY JSON FEATURE DISABLE,true); 
Property (CommonProperties .OUTBOUND CONTENT LENGTH BUFFER,20480); 
packages ("com.example.resource"); 
} 
} 


在 这 段 代码 中 ， 分 别 配置 了 禁用 自动 探测 feature、 支 持 JSR-353、 自 动 加 载 SPIl 和 支持 MOXy 的 JSON， 并 配置 了 响应 实体 缓存 的 大 小 为 20KB。 


10.3.2 ”服务 器 端 配置 


Jersey 提 供 的 服务 器 端 配置 类 org.glassfish.jersey.server.ServerProperties 位 于 jersey-server 包 内 。 在 应 用 中 通过 修改 通用 配置 的 值 ， 可 以 改变 Jersey 服 务 器 端的 默认 行为 。 如 禁用 不 必要 的 自动 探测 功 


能 ， 可 以 提高 系统 的 整体 性 能 。Jersey 服 务 器 端 配置 参数 见 表 10-2。 


表 10-2 Jersey 服务 器 端 配置 参数 列表 


常量 名 称 及 参数 名 称 说 明 
APPLICATION NAMEjersey.config.server.application. 应 用 名 称 ， 用 于 在 JMX 监控 中 的 唯一 标识 。 无 
name 默认 值 


BV_FEATURE DISABLEjersey.config.beanValidation. 
disable.server 

BV_DISABLE VALIDATE ON EXECUTABLE 
OVERRIDE CHECKjersey.config.beanValidation .disable. 
validateOnExecutableCheck.server 

BV_SEND ERROR IN RESPONSEJjersey.config. 
beanValidation .enableOutputValidationErrorEntity.server 


禁用 对 Bean Validation 的 支持 。 默 认 值 =false 


禁用 对 注解 @ValidateOnExecution 的 校 验 。 默 认 
值 =false 


启用 发 送 校 验 错误 信息 到 客户 端 。 默 认 值 =false 


常量 名 称 及 参数 名 称 
FEATURE _ AUTO DISCOVERY DISABLEjersey.config. 
disableAutoDiscovery.server 


HTTP METHOD OVERRIDEJjersey.config.server. 
httpMethodOverride 


JSON PROCESSING FEATURE DISABLE 
Jersey.config.disableJsonProcessing.server 


LANGUAGE MAPPINGSjersey.config.server.languageMappings 


MEDIA _TYPE MAPPINGSjersey.config.server. 
mediaTypeMappings 
METAINF_SERVICES LOOKUP DISABLEjersey.config 


.disable MetainfServicesLookup.server 


MOXY _ JSON FEATURE DISABLEjersey.config. 
disable MoxyJson.server 


MONITORING STATISTICS ENABLEDjersey.config. 


server .monitoring.statistics.enabled 


MONITORING STATISTICS MBEANS ENABLED jersey. 
config.server.monitoring.statistics.mbeans.enabled 


OUTBOUND CONTENT LENGTH BUFFER (Jersey 
2.2+) jersey.config.contentLength.buffer.server 


PROVIDER CLASSNAMESjersey.config.server.provider. 


classnames 


PROVIDER CLASSPATH]jersey.config.server.provider. 
classpath 


PROVIDER PACKAGESjersey.config.server.provider. 
packages 


PROVIDER SCANNING RECURSIVEjersey.config.server 


.provider.scanning.recursive 


RESOURCE VALIDATION DISABLEjersey.config.server 
resource.validation.disable 


RESOURCE VALIDATION IGNORE ERRORSjersey. 
config.server.resource.validation.ignoreErrors 


WADL FEATURE DISABLEjersey.config.server.wadl. 
disableWadl 


WADL GENERATOR CONFIGjersey.config.server.wadl. 


generatorConfig 


10.3.3 ”客户 端 配置 


Jersey 提 供 的 客户 端 配置 类 org.glassfish.jersey.client.ClientProperties 位 于 jersey-client 包 内 。 在 应 


可 以 提高 系统 的 整体 性 能 。Jersey 客 户 端 配置 参数 参见 表 10-3。 


( 续 ) 
说 明 
禁用 服务 器 端 对 feature 的 自动 探测 。 默 认 值 = 
false 
定义 HTTP 方法 覆盖 用 于 过 滤器 类 HttpMethod- 
OverrideFilter 


禁用 服务 器 端 对 Json Processing (JSR-353) feature 的 
文 持 。 默 认 值 =false 


定义 URI 扩 展 语言 匹配 。 用 于 过 滤器 类 Uri- 
ConnegFilter 

定义 URI 扩 展 媒体 匹配 。 用 于 过 滤器 类 Uri- 
ConnegFilter 


禁用 服务 器 端 对 META-INF/services 下 SPI 的 自 
动 加 载 。 默 认 值 =false 


禁用 服务 器 端 对 MOXyJson feature 的 支持 。 默 
认 值 =false 


启用 监控 统计 。 默 认 值 =false 


启用 JMX Mbeans 监控 统计 。 默 认 值 =false 


设置 响应 实体 缓存 的 大 小 和 响应 头 Content- 
Length 的 值 。 默 认 值 =8192 


指定 初始 的 Resource 和 Provider 类 名 


指定 初始 的 Resource 和 Provider 类 路 径 


指定 初始 的 Resource 和 Provider 类 所 在 的 包 名 


设置 包 扫描 递归 策略 。 默 认 值 =true 


禁用 Resource 验证 。 默 认 值 =false 


启用 忽略 资源 模型 校 验 错误 。 默 认 值 =false 


禁用 WADL 生成 。 默 认 值 =false 


定义 一 个 生成 WADL 的 provides，WadlGenerator 
类 的 实例 


中 通过 修改 通用 配置 的 值 ， 可 以 改变 Jersey 客 户 端的 默认 行为 。 如 禁用 不 必要 的 自动 探测 功能 ， 


表 10-3 Jersey 客 户 端 配 置 参 数列 表 


常量 名 称 及 参数 名 称 
ASYNC _ THREADPOOL SlZEjersey.config.client.async. 
threadPoolSize 
CHUNKED ENCODING SlZEjersey.config.client. 
chunkedEncodingSize 
CONNECT_TIMEOUTjersey.config.client.connectTimeout 


FEATURE AUTO DISCOVERY DISABLEjersey.config. 
disableAutoDiscovery.client 


FOLLOW _REDIRECTSjersey.config.client.followRedirects 


HTTP_URL CONNECTION SET_METHOD 


WORKAROUNDjersey.config.client.httpUrlConnection. 
setMethodWorkaround 

JSON_ PROCESSING FEATURE DISABLEjersey.config. 
disableJsonProcessing.client 

METAINF SERVICES LOOKUP DISABLEjersey.config. 
disableMetainfServicesLookup.client 

MOXY JSON FEATURE DISABLEjersey.config. 
disable MoxyJson.client 

OUTBOUND CONTENT LENGTH BUFFER (Jersey 
2.2+) jersey.config.contentLength.buffer.client 

READ TIMEOUTjersey.config.client.readTimeout 

SUPPRESS HTTP_ COMPLIANCE VALIDATION (Jersey 
2.2+) jersey.config.client.suppressHttpCompliance Validation 


USE_ ENCODINGjersey.config.client.useEncoding 


设 定 Grizzly 二 二 默认 
不 设置 

Chunked encoding 大 小 。 默 认 不 设置 

连接 超时 ， 单 位 毫秒 (ms)。 默 认 值 =0， 永 不 超时 

禁用 客户 端 自动 探测 特征 。 默 认 值 =false 


定义 客户 端 自动 重 定向 到 3xx 指定 的 URI。 默 认 
值 =true 


定义 客户 端 设置 不 支持 的 HTTP 方 法 到 Http 
URLConnection。 默 认 值 =false 


禁用 对 Json Processing ( JSR-353 ) 特征 的 支持 。 
默认 值 =false 

禁用 客户 端 对 META-INF/services 下 SPI 的 自动 
加 载 。 默 认 值 =false 

禁用 客户 端 对 MOXyJson 特征 的 支持 。 默 认 值 
=false 

设置 响应 实体 缓存 的 大 小 和 响应 头 Content- 
Length 的 值 。 默 认 值 =8192 

读 超 时 ， 单 位 毫秒 (ms)。 默 认 值 =0， 永 不 超时 

启用 忽略 客户 端 请 求 兼容 性 校 验 错 误 。 默 认 值 
=false 


指定 Content-Encoding 的 值 ， 指 定 值 类 型 为 
EncodingFilter。 默 认 不 指定 


10.4 _ Java 虚拟 机 调 优 


基于 JAX-RS 的 项 目 ， 通 常 要 关注 服务 器 和 开发 环境 的 Java 虚 拟 机 配置 。 日 常 的 关注 点 通常 是 内 存 溢 出 和 内 存 泄漏 。 为 了 更 好 地 解决 Java 虚 拟 机 这 个 


始 。 


10.4.1 ”虚拟 机 概述 


不 是 项 目 代码 问题 的 问题 ， 这 里 将 从 简 述 虚拟 机 开 


在 虚拟 机 加 载 类 之 前 ，Java 类 的 源 代码 首先 被 构建 工具 (如 Maven 等 ) 通过 调 


编译 器 javac 编 译 成 .class 字 节 码 文件 。 虚 拟 机 启动 时 ， 使 用 ClassLoader 以 双亲 委派 机 制 装载 类 的 字 节 码 文件 ， 链 接 到 


内 存 ， 然 后 对 类 进行 初始 化 (或 者 滞后 初始 化 ) 。 此 时 ，Java 类 就 进入 了 虚拟 机 的 内 


存 ， 我 们 的 关注 点 转 到 虚拟 机 的 内 存 模型 。 虚 拟 机 内 存 模型 示意 图 如 图 10-7 所 示 。 


Java 源 代码 文件 


执行 引 


掌 


(Java 字 节 码 指令 集 ) 


Class 字 节 码 文件 


方法 区 
Method Area 


加 载 
装载 -链接 -初始 化 


(ClassLoaden) 


loadClass findClass 
defineClass 
新 生 代 (New Generation) 


由 Eden Space 和 两 块 相 同 大 小 的 Survivor Space(S0 和 S1) 构 成 
-KNewSize -XOCMaxNewsSize -Xmn 


枝 


材 帆 
Stack Frame 


VM Stack 


PC 寄存 器 
Program 
Counter 
Register 


本 地 方法 材 
C 栈 : native 方 法 


JIT: native code 


栈 大 小 =256K-756K 


> , 线程 -村 
旧 生 代 (Old Generation) 方法 - 栈 由 


BR 


-Xms default= 物 理 内 存 的 1/64 得 小 于 1GB 


-Xmx default= 物理 内 存 的 1/4 但 小 于 1G8 


存 鸽 Java 对象、 数组 


图 10-7 Java 虚 拟 机 示意 图 


如 图 
在 JDK 8 中 被 驱除 出 JVM) 。 方 法 区 内 还 包括 常量 池 和 运行 时 常量 池 。 方 法 
回收 。 非 严格 来 说 ， 虚 拟 机 栈 、 本 地 方法 栈 以 及 PC 寄存 器 都 可 以 视 为 栈 。 虚 拟 机 栈 与 运行 期 
线程 的 方法 开辟 栈 帧 ， 栈 帧 用 于 存储 
方法 栈 又 称 C 栈 。 本 地 方法 本 同时 存储 JI 编译 的 方法 ， 这 类 方法 由 于 在 虚拟 机 栈 中 被 频繁 调 


二 记忆 
局 部 变量 、 


到 一 定 次 数 ， 


可 以 使 用 JDK 自 峙 


的 工具 jmap 和 jinfo 来 查看 项 目的 虚拟 机 配置 ， 示 例 代 码 如 下 。 


区 用 于 存储 类 信息 以 及 常量 和 静态 变量 等 信息 。 垃 圾 回收 器 对 堆 和 方法 
的 线程 对 应 ， 每 启动 一 个 线程 就 会 在 寄存 器 中 注册 一 个 指针 ， 指 向 内 存 中 为 其 开辟 | 
操作 数 栈 、 方 法 返回 值 等 信息 。 本 地 方法 栈 用 于 调用 操作 系统 相关 的 本 地 方法 接口 ， 本 地 方法 是 指使 用 native 关 键 字 修饰 、 使 用 C 语 言 实现 的 方法 ， 
此 被 JIT 编 译 成 本 地 方法 ， 


10-7 所 示 ，Java 庶 拟 机 大 体 上 可 分 为 堆 和 栈 两 部 分 。 其 中 ， 堆 用 于 存储 对 象 和 数组 ， 堆 内 的 资源 是 线程 共享 的 。 堆 细 分 为 新 生 代 、 旧 生 代 和 永久 代 ，SUN 的 虚拟 机 将 永久 代 和 方法 区 等 同 (永久 代 


区 的 回收 频率 是 不 同 的 ， 方 法 


区 内 的 资源 通常 不 会 被 频繁 


以 提高 性 能 。 


的 虚拟 机 栈 。 虚 拟 机 栈 内 会 为 
因此 本 地 


jmap -J-d64 -heap 6632 
Heap Configuration: 

MinHeapFreeRatio = 40 
MaxHeapFreeRatio = 70 


MaxHeapSize = 1073741824 
(1024.0MB 

) 

NewSize = 1310720 
(1.25MB 

) 

MaxNewSize = 17592186044415 MB 
Oldsize = 5439488 
(5.1875MB 

2 

NewRatio = 2 
SurvivorRatio =8 
PermSize = 21757952 
(20.75MB 

) 

MaxPermSize = 268435456 
(256.0MB 


) 
GlHeapRegionSize = 0 
(0.0MB 


) 


在 该 示例 中 ，- 上 d64 参 数 是 64， 为 JDK 使 用 的 参数 ，-heap 参 数 是 打印 堆 信息 ， 最 后 的 参数 是 pid， 可 以 通过 jps 等 方式 获得 。 使 用 


jinfo 查 看 JVM 的 详细 信息 的 示例 如 下 。 


A 

虚拟 机 参数 值 

jinfo -J-d64 -flags 6632 

-Dosgi .requiredJavaVersion=1.5 -Xms1024m -Xmx1024m -XX:MaxPermSize=256m 


SF 

堆 初 始 值 

jinfo -J-d64 -flag InitialHeapSize 6632 
—XX: InitialHeapSize=1073741824 


// 

堆 最 大 值 

jinfo -J-d64 -flag MaxHeapSize 6632 
—XX:MaxHeapSize=1073741824 

// 


新 生 代 初始 值 
jinfo -J-d64 -flag NewSize 6632 
—XX:NewSize=1310720 


de 

新 生 代 最 大 值 

jinfo -J-d64 -flag MaxNewSize 6632 
—XX:MaxNewSize=18446744073709486080 


// 

永久 代 初 始 值 

jinfo -J-d64 -flag PermSize 6632 
—XX:PermSize=21757952 


WA 

永久 代 最 大 值 

jinfo -J-d64 -flag MaxPermSize 6632 
—XX:MaxPermSize=268435456 


在 该 示例 中 ，“-flags” 打 印 显 式 定义 的 虚拟 机 参数 值 列表 ，“-flag 参 数 名 ”打印 某 项 参数 值 。 


在 日 常 开 发 和 调试 中 遇 到 的 栈 溢 出 时 ， 可 以 调整 虚拟 机 栈 参 数 -Xss， 但 如 果 虚 拟 机 栈 的 大 小 不 是 根本 问题 ， 


现 和 解决 问题 。 


对 于 处 理 堆 的 异常 或 者 错误 ， 通 常 可 归结 为 内 存 溢出 和 内 存 泄漏 这 两 个 方面 ， 浅 析 如 下 。 


10.4.2 ”内 存 溢出 与 内 存 汇 漏 


比如 递归 方法 中 不 适当 的 编码 产生 死 循 环 而 导致 的 栈 溢出 ， 那 么 还 需要 监控 和 跟踪 代码 来 发 


内 存 溢出 和 内 存 泄 漏 的 表象 都 是 系统 提供 的 内 存 空间 不 足以 支撑 应 用 的 运行 ， 但 两 者 的 实质 是 不 同 的。 前 者 可 以 理解 为 进入 虚拟 机 的 资源 总 量 比 出 去 的 资源 总 量 多 、 占 用 内 存 的 速率 要 快 于 垃圾 回收 的 


速率 ， 这 有 可 能 是 正常 的 业务 逻辑 ， 也 有 可 能 是 设计 上 的 缺陷 ;后 者 可 以 理解 为 进入 虚拟 机 的 某 些 资源 存在 引 


1. 内 存 溢出 


并 且 无 法 被 垃圾 回收 ， 虚 拟 机 失去 了 对 这 部 分 资源 的 回收 能 力 。 简 述 如 下 。 


内 存 溢出 的 原因 是 堆 的 大 小 无 法 承载 内 部 的 对 象 和 数组 了 。 这 个 问题 简单 地 说 ， 可 以 从 两 个 方面 解决 。 一 是 在 代码 中 减少 不 必要 的 实例 构造 ， 这 个 途径 会 直接 提高 项 目的 性 能 。 二 是 调整 堆 大 小 ，-Xms 
是 设置 堆 的 最 小 空间 的 参数 ，-Xmx 是 设置 堆 的 最 大 空间 的 参数 。 对 于 新 生 代 ， 空 间 的 设置 参数 为 -XX:NewSize 和 -XX:MaxNewSize， 当 -Xms 和 -Xmx 的 值 相同 时 ， 可 以 使 用 参数 -Xmn 来 简化 。 对 于 永生 代 
(SUN 虚 拟 机 对 应 的 是 方法 区 ) 的 设置 ， 初 始 空间 参数 为 -XX:PermSize， 最 大 空间 参数 为 -XX:MaxPermsize。 注 意 ， 虚 拟 机 一 旦 启动 ， 堆 的 总 大 小 就 被 固定 ， 无 法 动态 调整 。 


2. 内 存 泄漏 


内 存 泄漏 的 原因 是 垃圾 回收 器 无 法 对 存在 无 效 引用 的 对 象 进行 回收 导致 的 内 存 溢出 。 内 存 泄漏 没有 办 法 通过 设置 虚拟 机 参数 来 解决 ， 因 为 导致 这 一 问题 的 原因 来 自 编 码 阶段 ， 比 如 资源 在 使 用 完毕 后 没 
有 被 释放 等 。 解 决 这 一 问题 的 办 法 是 改进 代码 或 者 变更 依赖 包 (项 目的 依赖 包 并 不 总 是 让 人 放心 的 ) ， 发 现 问题 的 途径 不 一 而 足 ， 通 常 是 通过 分 析 工具 来 排查 泄漏 点 。 常 用 的 分 析 工具 见 表 10-4。 


表 10-4 Java 分析 工具 列表 


工具 名 称 


jvisualvm (Java Virtual Machine Monitoring, Troubleshooting， 


and Profiling TooD) 
JMC (Oracle Java Mission Control) 
MAT (Memory Analyzer) 


JProfiler 


YourKit Profiler 


获取 路 径 
JAVA_HOME/bin 


JAVA HOME/bin (JDK 7u40+) 

http://www.eclipse.org/mat 

http://www.ej-technologies.com/products/jprofiler/ 
overview.html 


http://www.yourkit.com 


分 析 过 程 包括 实时 监控 和 dump 快 照 两 种 ， 前 一 种 通过 工具 本 身 提供 的 GUI 界面 即 可 实现 ， 后 一 种 可 以 通过 JDK 自 带 的 工具 jimap 来 dump 当 前 虚拟 机 快照 ， 然 后 将 快照 文件 (本 例 是 Ubuntu 系统 下 


的 /var/local/my.mem.bin) 导入 分 析 工 具 ， 排 查 内 存 泄 漏 点 。 


在 Server 上 执行 : 


jmap -dump:format=b, file=mem.bin<pid> 


在 做 分 析 的 机 器 执行 : 


sudo scp root@server:/home/erichan/mem.bin /var/local/my.mem.bin 


另外 ， 也 可 以 通过 psi-probe 这 样 的 实时 工具 对 运行 期 的 服务 器 环境 进行 监控 。 下 面 给 出 psi-probe 的 安装 示例 。 


1) 下 载 ZIP 格 式 的 psi-probe 工 具 包 。 


下 载 
sudowget https://psi-probe.googlecode.com/files/probe-2.3.3.zip -P /opt 


2) 将 其 中 的 war 包 部 署 到 Tomcat 的 应 用 路 径 下 。 


// 

安装 

sudo unzip /opt/probe-2.3.3.zip -d /opt/ 

cp /opt/probe.war /opt/apache-tomcat-7.0.42/webapps/ 


3) 启动 Tomcat， 然 后 访问 该 工具 的 URL， 这 里 的 context 是 probe。 


// 
测试 
http://localhost:8080/probe/logs/index.htm 


由 于 篇 幅 所 限 ， 因 此 虚拟 机 的 部 分 到 此 结束 ， 读 者 可 以 找 来 专门 讲述 Java 虚 拟 机 的 书 来 学 习 。 


10.5 ”本章 小 结 


本 章 讲 述 了 使 用 Java 进 行 REST 开 发 中 需要 注意 的 性 能 和 优化 。10.1 节 讲述 了 HTTP 通 信 过 程 中 的 缓存 机 制 和 实践 ，10.2 节 讲述 了 何 时 使 用 以 及 如 何 优化 REST API 的 版 本 信息 ，10.3 节 讲述 了 Jersey 提 供 
的 参数 配置 ，10.4 节 简单 介绍 了 Java 虚 拟 机 的 情况 、 如 何 优化 其 配置 以 及 基本 的 JVM 问 题解 决 办 法 。 下 一 章 ， 我 们 开始 讲述 实现 JAX-RS 的 综合 示例 ， 即 基于 REST 式 的 Web 服 务 项 目 : 统一 自动 化 测试 平 


和 
= 


第 三 篇 ”实践 分 享 一 一 JAX-RS 2.0 


se 第 11 章 统一 自动 化 测试 平台 


第 11 章 ”统一 自动 化 测试 平台 


和 绽 公 
| 


本 书 的 最 后 一 章 是 一 个 综合 性 的 REST 式 Web 服 务实 例 ， 讲 述 如 何 使 用 Jersey 开 发 一 个 基于 JAX-RS 2.0 的 REST 式 的 Web 服 务 。 同 时 ， 在 这 个 过 程 中 ， 将 全 面 展示 前 面 10 章 所 述 的 知识 点 ， 并 与 读者 分 享 


敏捷 开发 、 持 续集 成 和 持续 部 署 等 项 目 管理 实践 。 我 们 要 开发 的 Web 服 务 是 一 个 统一 自动 化 测试 平台 ， 命 名 为 ATUP (Automation Test Unified Platform) ， 从 无 到 有 ， 为 读者 呈现 一 个 完整 的 应 用 。 


@@ 亲 诬 指南 ATUP 源 代码 地 址 : https://github.com/feuyeux/jax-rs2-atup 


11.1 ”ATUP 的 定义 


我 们 的 示例 分 为 3 个 部 分 : 需求 的 定义 、 设 计 和 交付 编码、 测试、 部署 。 首 先 我 们 从 需求 开始 。 


统一 自动 化 测试 平台 需 满足 如 下 特征 : 


“ATUP 应 确保 测试 项 目 和 测试 用 例 的 无 关 性 和 统一 性 ， 对 不 同 的 测试 平台 、 测 试 系统 和 测试 语言 应 使 用 统一 的 输入 和 输出 。 


: ATUP 应 支持 测试 的 类 型 包括 自动 化 测试 和 手动 测试 。 测 试 的 输入 和 输出 方式 统一 ， 手 动 应 和 自动 化 拥有 一 致 的 行为 。 


“ ATUP 对 测试 设备 的 管理 应 做 到 使 测试 设备 处 于 满 负 荷 工 作 ， 同 时 对 测试 设备 状态 进行 监控 ， 并 提供 告警 机 制 。 


“ ATUP 平 台 应 支持 对 测试 者 的 身份 管理 和 权限 控制 。 


11.1.1 需求 仓库 


基于 上 述 定义 ， 我 们 根据 Scrum 项 目 管理 方式 ， 首 先 收集 


户 的 需求 ， 着 手 建立 Backlog (需求 仓库 ) 。 为 了 演示 敏捷 开发 生命 周期 ， 我 们 将 ATUP 的 实现 在 两 个 迭代 周期 内 完成 ， 如 图 11-1 所 示 。 


Grooming 规划 任务 


回顾 


[= 
任务 回顾 


图 11-1 Scrum 开 发 管理 流程 


Grooming 


规划 


如 图 11-1 所 示 ，Backlog (需求 仓库 ) 是 实现 ATUP 的 源头 ， 每 个 迭代 (lteration) 开始 的 步骤 是 开 Grooming 会 议 ， 会 议 中 会 选择 仓库 中 优先 级 高 的 需求 并 定义 相关 的 用 户 故 事 (User Story) 。 


户 故 事 是 用 户 需求 的 单位 ， 用 以 标识 和 描述 用 户 需求 。 在 定义 用 户 故事 的 过 程 中 ， 产 品 负责 人 (Product Owner，PO) 作为 开发 团队 的 代表 和 用 户 一 起 明确 需求 的 内 容 、 可 行 性 等 信息 。 在 明确 
户 故 事后 ，PO 作 为 用 户 的 代表 和 开发 团队 一 起 在 Grooming 阶 段 明 确 需求 信息 ， 并 定义 用 户 故 事 的 验收 标准 和 优先 级 别 等 信息 。 


下 面 ， 我 们 模拟 设 定 ATUP 项 目的 Backlog 和 User Story。 
1.Backlog 列 表 
ATUP 项 目的 需求 仓库 包含 如 下 条 目 。 
“ 测试 用 例 (Test Case) : 它 是 测试 项 目的 基本 单位 。 测 试 集 (Test Suite) 是 测试 用 例 的 集合 ， 一 个 测试 集中 的 测试 用 例 是 一 个 统一 的 整体 。 测 试 者 可 以 自由 组 合 测试 用 例 到 测试 集 。 
“ 测试 作业 (TestJob) : 它 是 运行 时 的 测试 用 例 ， 测 试 设备 总 是 先 执 行 高 优先 级 的 作业 。 
“ 测试 结果 (Test Result) : 它 是 完成 时 的 测试 用 例 ， 用 来 记录 测试 作业 的 执行 情况 。 


“ 测试 设备 (Test Device) : 它 是 运行 测试 的 基本 单位 ， 测 试 平台 监控 设备 的 状态 和 在 其 上 的 测试 用 例 的 分 配 。 


:测试 者 〈Tester) : 它 的 身份 和 权限 由 平台 管理 员 分 配 。 


: 测试 设备 只 对 所 属 测 试 者 可 见 并 由 其 支配 。 


“ 测试 作业 和 测试 结果 只 对 所 属 测试 者 可 见 并 由 其 支配 。 


2. 用 户 故事 


US1 定 义 了 测试 集 和 测试 用 例 的 管理 和 显示 功能 。 其 描述 仅 作为 示范 ， 我 们 将 在 建 模 中 具体 描述 测试 集 和 测试 用 例 的 字段 等 信息 ， 见 表 11-1。 


表 11-1 测试 集 和 测试 用 例 用 户 故 事 


说 明 US1 
名 称 测试 集 和 测试 用 例 的 创建 、 修 改 、 显 示 
描述 作为 用 户 ， 我 希望 ATUP 可 以 提供 管理 测试 集 和 测试 用 例 的 Web 页 面 …… 昌 


“……"” 部 分 请 读者 自行 补充 完整 。 


US2 定 义 了 测试 作业 的 管理 和 显示 功能 ， 见 表 11-2。 


表 11-2 测试 作业 用 户 故事 


说 明 | US2 
名 称 


测试 作业 的 建立 、 显 示 ， 作 业 的 下 发 ， 失 败 作 业 的 重新 下 发 
描述 作为 用 户 ， 我 希望 ATUP 可 以 提供 管理 和 监控 我 的 测试 作业 的 Web 页 面 …… 


US3 定 义 了 测试 结果 的 管理 和 显示 功能 ， 见 表 11-3。 


表 11-3 测试 结果 用 户 故 事 


说 明 US3 


名 称 测试 结果 的 回 写 、 显 示 
曾 述 作为 用 户 ， 我 希望 ATUP 可 以 提供 我 的 测试 结果 显示 和 统计 的 Web 页 面 …… 


US4 定 义 了 测试 设备 的 管理 和 显示 功能 ， 见 表 11-4。 


表 11-4 测试 设备 用 户 故 事 


说 明 人 US4 
名 称 


测 试 设备 的 建立 、 显示 、 管理 
描述 作为 用 户 ， 我 希望 ATUP 可 以 提供 管理 和 监控 测试 设备 的 Web 页 面 …… 


US5 定 义 了 用 户 的 管理 和 显示 功能 ， 见 表 11-5。 


表 11-5 平台 用 户 管理 用 户 故事 


说 明 | US5 


名 称 测试 者 的 创建 、 修 改 、 显 示 
描述 作为 平台 管理 员 ， 我 希望 ATUP 可 以 提供 管理 ATUP 用 户 的 Web 页 面 …… 


11.1.2 需求 分 析 


对 于 我 们 熟知 的 瀑布 模型 中 的 需求 分 析 ，Scrum 框 架 的 Grooming 阶 段 与 之 最 为 接近 。 在 这 个 阶段 ，PO 会 代表 客户 或 者 同 客户 一 起 和 开发 团队 讨论 即将 到 来 的 迭代 中 要 完成 的 用 户 故事 。 


先 级 包括 最 高 到 最 低 的 若干 级 别 ， 通 常 低 于 中 级 的 用 户 故事 不 会 进入 Grooming 阶 段 ， 因 为 每 个 迭代 都 很 短小 ， 无 法 在 容纳 高 优先 级 用 户 故 事 的 同时 ， 做 低 优先 级 的 事情 。 


举例 来 说 ， 在 Grooming 阶 段 ，US1 被 定义 为 最 高 优先 级 ， 因 为 测试 集 和 测试 用 例 的 管理 和 显示 功能 是 实现 测试 平台 的 基础 功能 。US1 经 过 详细 讨论 后 ， 定 义 了 4 个 验收 标准 ， 见 表 11-6。 


表 11-6 测试 集 和 测试 用 例 用 户 故 事 分 析 


说 明 US1 
名 称 测试 集 和 测试 用 例 的 创建 、 修 改 、 显 示 
实现 测试 集 的 显示 功能 
验收 标准 实现 测试 集 的 增加 、 删 除 、 修 改 、 查 询 功 能 ， 测 试 集 非 空 时 不 能 删除 
实现 测试 用 例 显示 功能 
实现 测试 用 例 的 增加 、 删 除 、 修 改 、 查 询 功 能 
优先 级 别 疯 


户 故事 的 优 


US2 的 优先 级 也 是 最 高 的 ， 因 为 测试 作业 是 动态 的 测试 用 例 ， 是 从 下 发 到 完成 测试 的 中 间 状 态 ， 所 以 在 测试 平台 的 功能 开发 中 非常 紧急 而 重要 。US2 定 义 了 三 个 验收 标准 分 别 用 于 验收 测试 作业 的 定 


义 、 监 控 和 容错 ， 见 表 11-7。 


表 11-7 测试 作业 用 户 故 事 分 析 


说 明 | US2 


名 称 测试 作业 的 建立 、 显 示 ， 作 业 的 下 发 ， 失 败 作业 的 重新 下 发 

实现 用 户 根据 所 属 的 测试 集 ， 定 义 测试 作业 类 型 。 测 试 作业 类 型 包括 即时 下 发 、 延 时 下 发 和 周 
期 下 发 3 种 类 型 ， 测 试 作业 优先 级 包括 高 、 中 等 和 低 3 个 级 别 

实现 用 户 对 所 属 测试 作业 列表 的 监控 功能 

实现 用 户 对 失败 的 所 属 测试 作业 重新 下 发 功能 
优先 级 别 最 高 


验收 标准 


US3 的 优先 级 是 高 。 虽 然 测 试 结果 是 用 户 最 终 要 得 到 的 输出 ， 而 前 述 的 两 个 用 户 故事 都 是 输入 和 过 程 环节 ， 但 在 整个 系统 的 开发 进程 中 ， 测 试 结果 是 重要 但 不 紧急 的 需求 ， 其 基于 的 前 提 更 为 紧急 。 测 
试 结果 的 验收 标准 包括 记录 、 查 询 和 统计 ， 见 表 11-8。 


表 11-8 ”测试 结果 用 户 故事 分 析 


说 明 | i 


名 称 测试 结果 的 回 写 、 显 示 

一 个 测试 作业 一 旦 下 发 就 必须 有 一 个 测试 结果 ， 无 论 是 否 成 功 或 者 超时 
验收 标准 实现 用 户 对 所 属 测试 结果 的 查询 功能 

实现 用 户 对 所 属 测试 结果 的 统计 功能 
优先 级 别 高 


US4 的 优先 级 是 最 高 ， 因 为 测试 作业 的 下 发 要 依赖 于 测试 设备 。 验 收 标准 包括 用 户 和 管理 员 对 设备 的 配置 和 监控 ， 见 表 11-9。 


表 11-9 测试 设备 用 户 故 事 分 析 


说 明 | US4 


名 称 测试 设备 的 建立 、 显 示 、 管 理 
实现 用 户 对 所 属 设备 的 配置 和 监控 功能 
验收 标准 实现 管理 员 对 设备 的 定义 与 分 配 功能 
测试 设备 的 实时 状态 显示 无 误 。 只 有 测试 队列 中 没有 相关 的 测试 作业 ， 测 试 设备 才 会 空闲 
优先 级 别 最 高 


US5 的 优先 级 是 高 ， 因 为 测试 者 的 管理 、 注 册 、 登 录 ， 以 及 权限 分 配 等 功能 都 是 重要 而 不 紧急 的 。 作 为 示例 ， 这 部 分 被 弱化 了 ， 其 实 该 用 户 故事 的 验收 标准 可 以 列举 出 很 多 ， 这 里 US5 以 一 条 验收 标准 
来 代 指 完成 上 述 US1~US4 的 几 个 功能 点 ， 见 表 11-10。 


表 11-10 平台 用 户 管理 用 户 故 事 分 析 


名 称 测试 者 的 创建 、 修 改 、 显 示 
验收 标准 实现 管理 员 对 ATUP 用 户 的 维护 
优先 级 别 高 


11.1.3 ”迭代 规划 


作为 开发 者 ， 首 先 会 想到 作为 一 个 从 无 到 有 的 项 目 ， 有 许多 基础 工作 要 做 ， 比 如 环境 搭建 、 技 术 调 研 、 原 型 测试 ， 以 及 通用 的 核心 代码 编写 。 但 作为 用 户 ， 他 只 关心 所 需 的 功能 是 否 实现 ， 运 行 是 否 稳 
、 高 效 。 因 此 ， 开 发 者 以 “小 步 快 跑 ” 的 迭代 开发 来 交付 功能 给 用 户 是 最 终 目 的 ， 从 而 ， 我 们 的 基础 工作 应 该 以 每 次 够 用 就 好 ， 以 不 断 重 构 完善 的 方式 来 推动 。 


lal 


1. 用 户 故事 与 迭代 


lteration 就 是 一 次 迭代 ， 是 开发 周期 的 基本 单位 ， 通 常 为 2~3 周 。 每 个 lteration 的 权重 与 开发 者 人 数 、 每 日 工作 时 等 信息 相关 ， 这 里 假定 参考 值 为 15， 那 么 在 做 计划 时 ， 累 计 的 用 户 故 事 的 权重 达到 参 
考 值 ， 就 不 再 加 新 的 用 户 故事 到 当前 的 teration 中 。 作 为 示例 ， 我 们 将 ATUP 系 统 的 开发 分 为 两 个 迭代 完成 ， 每 个 迭代 实现 的 用 户 故 事权 重 之 和 为 12， 见 表 11-11~ 表 11-15。 


表 11-11 用 户 故 事 的 权重 1 


US_ID US1 


名 称 测试 集 和 测试 用 例 的 创建 、 修 改 、 显 示 
迭代 编号 Iteration-1 
权重 6 

表 11-12 用 户 权重 故事 2 
US_ID US2 
名 称 测试 作业 的 建立 、 显 示 ， 作 业 的 下 发 ， 失 败 作 业 的 重新 下 发 
迭代 编号 Iteration-1 
权重 6 

表 11-13 ”用户 权 重 故 事 3 
US ID US3 
名 称 测试 结果 的 回 写 、 显 示 
迭代 编号 Iteration-2 
权重 3 

表 11-14 用 户 权 重 故 事 4 
US_ID US4 
名 称 测试 设备 的 建立 、 显 示 、 管 理 
迭代 编号 Iteration-2 
权重 6 

表 11-15 用户 权重 故事 5 
US ID US5 
名 称 测试 者 的 创建 、 修 改 、 显 示 
迭代 编号 Iteration-2 
权重 3 

2. 规 划 迭 代 任务 


Planning 是 在 lteration 定 义 好 用 户 故事 后 ， 对 其 进行 任务 定义 的 规划 过 程 。 任 务 会 被 分 配 到 即将 到 来 的 Sprint 中 。Sprint 是 开发 周期 的 最 小 单位 ， 通 常 一 次 迭代 包含 1~2 个 Sprint。 每 个 Sprint 开始 前 都 
会 有 一 次 Planning 来 细 化 用 户 故 事 ， 粒 度 精 确 到 可 执行 /可 编码 的 任务 。 


一 个 任务 是 一 个 用 户 故事 可 执行 的 基本 单位 ， 是 对 验收 标准 的 分 步 实 现 。 可 以 在 任务 开始 前 指定 负责 人 ， 也 可 以 在 敏捷 开发 过 程 中 动态 分 配 。 任 务 的 状态 从 定义 到 完成 可 以 有 定义 、 处 理 中 、 完 成 和 被 
阻塞 等 多 种 状态 。 每 个 任务 包括 一 到 多 个 的 测试 集 和 测试 用 例 。 没 错 ， 我 们 的 自动 化 测试 平台 的 开发 也 需要 CI 构建 和 自动 化 测试 ， 因 为 自动 化 测试 是 履行 敏捷 开发 的 重要 组 成 部 分 。 作 为 示例 ， 我 们 只 列举 
测试 集 和 测试 用 例 建 模 一 个 任务 的 定义 ， 见 表 11-16。 


表 11-16 测试 集 和 测试 用 例 建 模 任务 


用 户 故 事 US1: 测试 集 和 测试 用 例 的 创建 、 修 改 、 显 示 
TA_ID TAI1 
名 称 测试 集 和 测试 用 例 建 模 
定义 用 户 、 测 试 集 和 测试 用 例 的 数据 库 模型 
描述 定义 用 户 、 测 试 集 和 测试 用 例 对 应 的 Java 类 


JPA 实现 数据 库 CRUD 
工时 评估 12 小 时 (2 人 /日 ) 
负责 人 xxx 


11.2 ATUP 的 设计 


在 完成 用 户 故 事 的 定义 后 ， 开 发 团队 要 基于 本 节 讲述 的 敏捷 流程 来 对 需求 做 概要 和 详细 设计 ， 这 里 其 实 还 包括 了 技术 选 型 和 部 署 拓 扑 设计 。 


11.2.1 开发 和 部 署 环境 


我 们 根据 用 户 故 事 和 自身 开发 特征 ， 选 用 三 组 开发 工具 和 平台 : 开发 、 测 试 和 部 署 运行 ， 见 表 11-17。 


表 11-17 ATUP 环 境 与 工具 


项 目 版 本 
0 
静态 页 面部 团 
REST 式 的 Web 服务 部 团 7.0.42 
数据 库 56 
构建 工具 3.1.1 
版 本 控制 1.8.1 
集成 测试 (CD 平台 
信友 质量 和平 

( 续 ) 

EE 和 
开发 环境 (Development) 
开发 平台 13.10 
测试 环境 (Staging) 
测试 平台 13.10 
产品 环境 (Production ) 
测试 平台 13.10 


1.Intellij IDEA 配 置 


1DEA 并 非 ATUP 唯 一 可 以 使 用 的 IDE， 但 是 其 智能 和 便捷 的 体验 相对 其 他 IDE 较 好 ， 因 此 在 本 书 最 后 一 章 ， 笔 者 还 是 推荐 将 完整 示例 运行 在 IDEA 上 。 开 发 服务 器 使 用 omcat 7， 这 个 争议 要 少 很 多 ， 毕 


竟 目前 Servlet 容 器 没有 比 Tomcat 更 流行 的 了 。 在 IDEA 中 配置 使 用 romcat 和 在 其 他 IDE 中 差别 不 大 ， 如 图 11-2 所 示 。 


Name: DD share 


Server Deployment | Logs | Code Coverage | Startup/Connection | 


Application server: | Tomcat 7.0.42 园 


Open browser 


[Vi After launch 加 DOD with lavaScript debugger 
http://localhost:8080/atup-device/ 图 


VM options: -Xms1024m -Xmxl1024m -XX:PermSize=512m -XX:MaxPermSize=1024m 


图 11-2 IDEA 内 置 Tomcat 配 置 


如 图 11-2 所 示 ， 在 服务 器 配置 页 面 ， 为 开发 服务 器 配置 了 虚拟 机 参数 ( 见 图 11-2 所 示 下 方 的 “VM options”) ， 这 步 的 目的 是 扩大 JVM 堆 的 大 小 ， 以 承载 更 多 的 对 象 实例 化 。 否 则 ， 会 在 调试 阶段 出 
现 堆 内 存 溢出 的 问题 。 虚 拟 机 配置 的 参考 参数 如 下 ， 可 根据 本 机 情况 调整 。 


—Xms1024m -Xmx1024m -XX:PermSize=512m -XX:MaxPermSize=1024m 


在 部 署 页 面 ， 需 要 指定 各 模块 的 context 名 称 和 加 载 顺 序 ， 如 图 11-3 所 示 。 


er EY 
Server Deploymend| Logs | code coverage | Startup/Connection | 


Deploy at the server startup 
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p 
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图 11-3 ATUP 模 块 部 署 设置 


如 图 11-3 所 示 ，ATUP 包 含 5 个 war 包 ， 分 别 是 REST 交 互 页 面 模块 atup-page、 设 备 管理 模块 atup-device、 用 户 管理 模块 atup-user、 用 例 管理 模块 atup-case， 以 及 测试 平台 模块 atup-test-station。 


如 果 做 一 键 发 布 ， 模 块 部 署 顺 序 可 参考 图 11-3。 需 要 指出 的 是 ，atup-core 是 jar 包 ， 是 这 5 个 war 包 的 底层 支持 模块 ， 无 须 部 署 。 


2.Tomcat 配 置 


完成 1DE 配 置 后 ， 为 了 运行 ATUP 示 例 ， 我 们 需要 修改 Tomcat 的 配置 。 这 里 只 需要 设置 两 个 Tomcat 配 置 : 一 个 是 在 Tomcat 的 上 下 文中 添加 JDBC 的 数据 源 ( 必 选 ) ， 另 一 个 是 设置 JVM 的 参数 以 支持 更 


大 的 堆 存储 空 间 (可 选 ) 。 


看 要 在 TOMCAT_HOME/conf/context.xml 中 添加 如 下 配置 。 


3 


为 了 添加 JDBC 数 据 源 ， 


<Context> 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
<Resource name="jdbc/AtupDataSource" 

auth="Container" 

type="javax.sql.DataSource" 

driverClassName="org.gjt.mm.mysql .Driver™ 

url="jdbc:mysql://localhost:3306/jaxrs2_atup" 

Username="root" 

Password="root" 

maxActive="20" 


maxIdle="10" 
maxWait="-1" /> 
</Context> 


在 这 段 代 码 中 ， 定 义 了 MySQL 数 据 库 驱动 、 数 据 schema 为 jaxrs2_atup， 以 及 用 户 名 和 密码 是 root 等 。 


为 了 设 定 JVM 参 数 ， 需 要 修改 TOMCAT_HOME/bin/catalina.sh 文 件 (Windows 平 台 是 catalina.bat 文 件 ) ， 添 加 如 下 配置 。 


JAVA_OPTS= 
‘~-server -Xms1024m -Xmx1024m -XX:PermSize=128m -XX:MaxNewSize=256m -XX:MaxPermSize=256m 
’ 
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.2.2 ”模块 定义 和 拓扑 


ATUP 是 使 用 Maven 管 理 的 多 模块 项 目 。 父 模块 负责 定义 子 模块 构建 顺序 、 依 赖 包 版 本 定义 、 依 赖 包 仓库 定义 及 构建 、Profile 等 多 模块 通用 配置 。ATUP 父 模块 的 Maven 坐 标 信息 如 下 所 示 。 


<groupId>org. feuyeux.jaxrs2.atup</groupId> 
<artifactId>atup</artifactId> 
<packaging>pom</packaging> 
<version>0.0.2-SNAPSHOT</version> 


<name>ATUP Project Parent</name> 


ATUP 父 模块 定义 了 6 个 子 模块 ， 示 例 代 码 如 下 所 示 。 


<modules> 
<module>atup-core</module> 
<module>atup-device</module> 
<module>atup-user</module> 
<module>atup-case</module> 
<module>atup-test-station</module> 
<module>atup-page</module> 

</modules> 


在 这 段 代 码 中 ，atup-core 是 核心 功能 模块 ， 负 责 提供 REST 式 的 Web 服 务 中 的 基础 和 通用 的 代码 实现 。atup-device 是 测试 设备 模块 。atup-user 是 用 户 管理 模块 。atup-case 模 块 用 于 实现 测试 集 、 测 
试用 例 、 测 试 作业 和 测试 结果 。atup-page 模 块 是 ATUP 系 统 的 用 户 界面 模块 ， 是 纯 HTML 实 现 的 。 严 格 来 说 atup-test-station 模 块 ， 不 是 ATUP 系 统 的 组 成 部 分 ， 只 是 为 了 演示 ATUP 系 统 和 测试 平台 的 交 
互 ， 以 及 测试 ATUP 平 台 的 测试 作业 和 测试 结果 的 工作 状态 。 


ATUP 的 依赖 包 版 本 信息 定义 如 下 所 示 。 


<properties> 
<JDK.version>1.7</JDK.version> 
<jersey.version>2.9</jersey.version> 
<junit.version>4.11</junit.version> 
<10g4j .version>2.0-beta9</10g4j .version> 
<spring.version>3.2.5.RELEASE</spring.version> 
<eclipselink.version>2.5.0</eclipselink.version> 
<jquery.version>2.0.3</jquery.version> 


在 这 段 代 码 中 ， 定 义 了 JDK 版 本 为 1.7、Jersey 版 本 为 2.9、 单 元 测试 工具 JUnit 版 本 为 2.4.1、 日 志 工 具 Log4 版 本 为 2.0-beta9、loC 和 事务 管理 容器 Spring 版 本 为 3.2.5.RELEASE、JPA 参 考 实现 
EclipseLink 版 本 为 2.5.0， 以 及 静态 页 面 脚本 库 jQuery 版 本 为 2.0.3。 


ATUP 采 用 动静 分 离 的 部 署 方式 。 静态 页 面 模块 atup-page 部 署 在 Nginx 服 务 器 上 ， 为 不 同 身份 的 用 户 提供 访问 并 控制 访问 权限 (后面 讲述 原因 ) 。 用 户 、 设 备 和 测试 用 例 分 别 部 署 在 独立 的 Tomcat 服 
务 器 上 ， 以 便 分 担 压 力 (作为 演示 项 目 ， 部 署 都 是 单 点 的 ， 演 示 项 目 实际 上 支持 大 用 户 的 并 发 访问 比较 困难 ) 。 作 为 演示 项 目 ， 数据库 服务 器 只 部 署 一 台 ， 为 全 部 模块 提供 数据 。 测 试 平台 模块 atup-test- 
station 单 独 部 署 ， 作 为 演示 也 使 用 Tomcat 服 务 器 一 一 对 于 ATUP 而 言 ， 只 要 提供 REST 式 的 Web 服 务 即 可 ， 并 不 关心 其 实现 。ATUP 的 拓扑 如 图 11-4 所 示 。 


如 图 11-4 所 示 ，ATUP 分 别 部 署 在 Nginx、Tomcat 上 ， 数 据 库 部 署 在 MySQL 上 ， 测 试 平 台 (又 称 执行 机 ) 通常 部 署 在 Linux 系 统 ， 可 以 是 Tomcat 上 的 Servlet 应 用 (比如 Jenkins 的 Slave) ， 也 可 以 是 
Python、Ruby、Perl、TCL 等 设备 通信 的 脚本 环境 。4 种 角色 的 用 户 将 通过 Nginx 进 入 ATUP 系 统 。 
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ATUP-TEST-STATION 
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图 11-4 ATUP 部 署 拓扑 


11.2.3 ”持续 集成 流程 


从 狭义 上 讲 ， 持 续集 成 流程 是 对 应 用 集成 测试 持续 进行 的 流程 ， 流 程 的 核心 是 对 集成 本 身 的 持续 ; 从 广义 上 讲 ， 已 不 是 这 个 名 词 本 身 的 含义 ， 包 括 了 对 部 署 和 交付 的 持续 。 因 为 如 果 持 续集 成 做 得 
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那么 可 以 做 到 通过 持续 进行 的 集成 测试 后 的 产品 是 可 以 直接 部 署 上 线 的 ， 上 线 的 产品 是 可 以 满足 用 户 需 求 的 。 所 以 ， 持 续 发 布 和 持续 交付 是 对 持续 集成 的 延伸 和 肯定 。 下 面 我 们 结合 这 一 理论 完成 对 ATUP 持 


续集 成 的 设计 。 


1. 持 续集 成 


ATUP 的 持续 集成 伴随 着 敏捷 开发 的 进程 进行 。 每 个 功能 点 开发 完毕 ， 必 须 进 行 单元 测试 ， 确 保 代码 的 功能 性 没有 问题 ， 然 后 向 版 本 控制 服务 器 提交 代码 。 每 次 向 版 本 控制 服务 器 提交 都 会 触发 一 次 CI 构 


建 ， 包 括 编译 、 基 础 功能 测试 和 打包 。 在 这 个 过 程 中 ,会 对 项 目 进行 单元 测试 和 集成 测试 。 同 时 ，ClI 服 务 器 Jenkins 会 使 用 代码 覆盖 率 工具 检查 当前 版 本 中 代码 被 测试 的 覆盖 情况 ，Jenkins 还 会 触发 代码 质 


量 管理 平台 SonarQube 以 检验 当前 版 本 代码 的 质量 。 例 如 ， 在 每 天 夜间 ，Jenkins 会 周期 性 地 启动 Nightly 构 建 ， 包 括 编译 、 全 量 测试 和 打包 。 在 这 个 过 程 中 ， 会 对 项 目 额外 进行 系统 测试 。 在 每 个 开发 迭代 


结束 前 ， 会 对 这 个 迭代 的 开发 进行 功能 性 和 性 能 测试 。 


2. 持 续 发 布 和 交付 


ATUP 的 持续 发 布 通常 会 发 生 在 每 个 迭代 结束 前 。 在 测试 通过 后 ，DevOps 人 员 会 触发 Jenkins 的 自动 部 署 作 业 ， 将 构建 好 的 当前 项 目 部 署 到 Staging 环 境 。 然 后 ， 在 Staging 环 境 中 ， 开 发 团队 需要 对 其 


进行 GUI 自动 化 测试 和 手动 测试 以 校 验 其 功能 性 ， 同 时 ， 启 动 自动 化 测试 脚本 来 对 其 进行 压力 测试 。 当 Staging 环 境 中 的 项 目测 试 通过 后 ，DevOPps 人 员 会 将 这 个 版 本 的 项 目 部 署 到 Production 环 境 。ATUP 


的 持续 发 布 模型 如 图 11-5 所 示 。 
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图 11-5 ”ATUP 持 续 发 布 示 意图 


在 图 11-5 中 ， 根 据 服务 器 用 途 可 以 划分 为 上 下 两 类 ， 图 上 部 的 机 器 用 于 部 署 ATUP 应 用 ， 包 括 静 态 应 用 服务 器 、 应 用 服务 器 和 数据 库 服 务 器 ;图 下 部 的 机 器 用 于 开发 管理 ， 包 括 Maven 私 服 、Git 私 服 、 


持续 集成 服务 器 、 代 码 评审 和 代码 质量 计算 服务 器 。 


ATUP 的 持续 交付 流程 发 生 在 迭代 结束 时 ， 在 这 个 阶段 会 对 这 次 迭代 中 定义 的 每 个 用 户 故事 进行 验收 测试 。 当 用 户 接收 后 ， 这 次 的 交付 流程 即 宣告 完毕 。 


11.3 ATUP 的 实现 


ATUP 的 实现 包括 三 个 部 分 。 首 先 实现 的 是 通用 的 核心 模块 ， 包 括 数 据 库 配置 与 访问 、REST 客 户 端的 封装 、 用 户 验 证 和 权限 、 作 业 分 派 以 及 持续 发 布 的 统一 配置 。 接 下 来 是 用 户 模块 、 设 备 模 块 、 


模块 和 静态 页 面 模块 等 模块 功能 的 实现 。 最 后 实现 各 模块 的 持续 交付 ， 使 其 成 为 一 个 产品 。 


11.3.1 Sprint1 核 心 功 能 


本 节 讲 述 ATUP 的 核心 模块 atup-core 的 实现 是 Sprint1 的 工作 内 容 ， 将 在 本 节 作为 Sprint1 的 实现 示例 来 讲 。 每 个 步骤 会 根据 前 述 的 用 户 故 事 和 迭代 规划 中 的 优先 级 来 进行 。 


例 


1 数据 库 持久 层 


根据 前 述 的 进 代 任务 ， 优 先 级 最 高 的 就 是 设计 并 实现 数据 库 和 相关 模块 的 数据 表 。 由 于 我 们 使 用 PA 和 MySQL 来 实现 ， 因 此 首先 讲述 各 个 表 的 设计 ， 然 后 是 JPA 的 配置 ， 最 后 简要 介绍 MySQL 的 配置 。 


(1) 测试 集 和 测试 用 例 类 设计 


测试 集 和 测试 用 例 是 统一 测试 平台 的 核心 类 ， 我 们 先 从 这 里 开始 。 测 试 集 的 最 简 设 计 应 包括 测试 集 ID、 名 称 、 状 态 和 类 型 。 测 试 集 实体 类 代码 片段 如 下 所 示 。 


Q@Entity 

QTable (name = "test suite")// 

关注 点 1 加 

: 表 和 实体 映射 的 注解 

public class AtupTestSuite implements Serializable { 
人 7 

关注 点 2 

: 主键 字段 的 注解 定义 


QId 
Q@GeneratedValue (strategy = GenerationType.IDENTITY, generator = "EMP SEQ") 
@SequenceGenerator (name = "EMP SEQ") 
@Colum (unique = true, nullable = false, name = "suite id") 
public Integer getSuiteId() { 
return SuiteId; 


@Column (name = "suite name", unique = true) 
public String getSuiteName () { 
return suiteName; 

} 

@Column (name = "suite type") 
public Integer getSuiteType() { 
return suiteType; 

} 

QColumn (name = "suite status") 
public Integer getSuiteStatus () { 
return suitestatus; 

} 

i 


在 这 段 代 码 中 ，@Table 注 解 将 类 对 应 到 test_suite 表 ， 见 关注 点 1; @Column 将 类 的 属性 对 应 到 test_suite 表 的 字段 ， 其 中 主键 字段 为 suite id，unique=true 代 表 唯 一 ，nullable=false 代 表 非 空 。 该 
字段 根据 数据 库 的 sequence 自 增 ， 见 关注 点 2。 


此 外 ， 为 了 方便 查询 ， 我 们 定义 了 JPA 的 名 称 查询 findBySuiteStatus 和 findBySuiteName， 分 别 根据 测试 集 状 态 和 测试 集 名 称 返 


回 


该 表 的 数据 集 ， 定 义 如 下 所 示 。 


QNamedqoueries ({ 

@NamedQuery (name = "findBySuitesStatus", 

query = "SELECT testSuite FROM AtupTestSuite testSuite 
WHERE testSuite.suiteStatus= :suiteStatus"), 
@NamedQuery (name = "findBySuiteName", 

query = "SELECT testSuite FROM AtupTestSuite testSuite 
WHERE testSuite.suiteName= :suiteName")}) 


接 下 来 是 测试 集 的 数据 表 test_suite 的 DDL， 示 例 代 码 如 下 所 示 。 


CREATE TABLE “test_suite 
( 
“suite id” int 
(11 
) NOT NULL AUTO INCREMENT, 
‘suite name. varchar 
(255 
) DEFAULT NULL, 
‘suite status” int 
L 
) DEFAULT NULL, 
“suite type. int 
(11 
) DEFAULT NULL, 
PRIMARY KEY 
(suite id“ 
1 
UNIQUE KEY ‘suite id. 
(“suite jd“ 


’ 
UNIQUE KEY ‘suite name. 
(‘suite name. 


) ENGINE=InnoDB DEFAULT CHARSET=utf87 


在 这 段 代码 中 ， 定 义 了 最 简 的 4 个 字段 : 主键 、 测 试 集 名 称 、 测 试 集 状态 和 测试 集 类 型 。 为 了 简便 ， 我 们 没有 为 测试 集 的 各 种 状态 和 类 型 单独 建立 表 。 测 试 集 的 状态 包括 : 可 用 (1) 和 禁用 (0) 。 测 
试 集 的 类 型 包括 : 普通 测试 集 、 性 能 测试 集 和 边缘 测试 集 ， 示 例如 下 所 示 。 


* NORMAL, SUITE=1 

* PERFORMANCE_SUITE=2 

“EDGE_SUITE=3 

详情 可 参见 org.feuyeux.jaxrs2.atup.core.constant.AtupParam 接 口 。 


为 了 更 方便 演示 ATUP， 我 们 为 测试 集 表 创 建 初始 测试 集 ， 内 容 如 下 所 示 。 


INSERT INTO ‘jaxrs2 atup'. test suite. 

(‘suite id', “suite name', “suite status', ‘suite type') 
VALUES — 下 加 

(1, 'Performance Test',1,2), 

27"OUI Test dd1T)7 

3,'Unit Test',1,1), 

4,'Integration Test',1,1), 


( 
( 
( 
(5, "System Test',1,1); 


讲述 完 测试 集 ， 接 下 来 介绍 测试 用 例 。 包 含 于 测试 集 的 测试 用 例 ， 其 最 简 信 息 包括 测试 用 例 1D、 名 称 、 内 容 、 状 态 以 及 所 属 的 测试 集 。 此 外 ， 我 们 为 其 添加 了 创建 时 间 和 最 后 修改 时 间 。 测 试用 例 实体 
类 代码 片段 如 下 所 示 。 


@Entity 
@Table 
(name = "test_case" 


public class AtupTestCase implements Serializable { 
@Id 
Q@GeneratedValue 


(strategy = GenerationType.IDENTITY, generator = "EMP SEQ" 
) 3 


@SequenceGenerator 
(name = "EMP SEQ" 
) 
@Column 
(unique = true, nullable = false, name = "case_id" 


public Integer getCaseId() { 
return caseId7 


@Colummn 
(name = "case name", unique = true 


public String getCaseName () { 
return caseName; 


Ion // 
注 点 1 
则 试用 例 和 测试 集 的 多 对 一 关系 注解 


QJoinColumn 
(name = "suiteId" 
) 
public AtupTestSuite getSuite() { 
return suite; 


@Column 
(name = "case body" 
) 
Q@XmlAttribute 
public String getCaseBody() { 
return caseBody; 


Column 
(name = "create time" 
) 

@XxmlJavaTypeAgdapter 
(JaxbDateSerializer.class 


public Date getCreateTime() { 
return createTime; 

} 

Q@Column 
(name = "update time" 
) 

@XxmlJavaTypeAdapter 
(JaxbDateSerializer.class 
) 
public Date getUpdateTime() { 
return updateTime; 

} 

@Colummn 
(name = "case_status" 
) 
public Integer getCaseStatus() { 
return caseStatus; 


} 


这 段 代 码 与 测试 集 类 似 ， 额 外 要 说 明 的 是 ， 测 试用 例 和 测试 集 是 多 对 一 (ManyToOne) 的 关系 ， 即 多 个 测试 用 例 属于 一 个 测试 集 ， 见 关注 点 1。 


此 外 ， 为 了 方便 查询 ， 我 们 定义 了 JPA 的 名 称 查 询 findByStatus 和 findByName， 分别 根 据 测试 用 例 状 态 和 名 称 返回 该 表 的 数据 集 ， 定 义 如 下 所 示 。 


@NamedQueries ({ 


@NamedQuery (name = "findByStatus", 
query = "SELECT testCase FROM AtupTestCase testCase WHERE testCase.caseStatus= :caseStatus"), 
@NamedQuery (name = "findByName", 


query = "SELECT testCase FROM AtupTestCase testCase WHERE testCase.caseName= :caseName")}) 


接 下 来 是 测试 用 例 的 数据 表 test_case 的 DDL， 示 例 代码 如 下 所 示 。 


CREATE TABLE ‘test case. ( 
‘case id. int (11) NOT NULL AUTO_INCREMENT, 
‘case name ”varchar (255) DEFAULT NULL, 
‘case body. varchar (255) DEFAULT NULL, 
‘case_ status. int (11) DEFAULT NULL, 
‘create time ”datetime DEFAULT NULL, 
‘update _ time ”datetime DEFAULT NULL, 
“suiteId ”int(11) DEFAULT NULL, 
PRIMARY KEY (‘case id), 
UNIQUE KEY ‘case id (‘case id), 
UNIQUE KEY ‘case _ name” (“case name’), 
KEY ‘FK test case suitelId. (`suiteId `)， 
CONSTRAINT ‘FkK test case suiteId’ FOREIGN KEY (`suiteId `) 
REFERENCES ‘test suite. (suite id`) 

) ENGINE=InnoDB DEFAULT CHARSET=utf8; 


对 于 这 段 代码 要 额外 说 明 的 是 ， 测 试 状态 包括 : 正常 (0) 和 禁用 (1) ， 详 见 org.feuyeux.jaxrs2.atup.core.constant.AtupParam 接 口 。 


(2) 用 户 类 设计 


类 用 于 ATUP 系 统 标识 当前 操作 者 的 身份 ， 其 最 简 信息 包括 用 户 ID、 名 和 了 密码。 此外， 我 们 添加 了 用 户 角 色 和 用 户 状态 。 该 类 的 代码 片段 如 下 所 示 。 


Q@Entity 
@Table 
(name = "atup user" 
) 
public class AtupUser implements Serializable { 
@Id 
Q@GeneratedValue 
(strategy = GenerationType.IDENTITY, generator = "EMP_ SEQ" 
) 


@SequenceGenerator 
(name = "EMP SEQ" 
) 2 
@Column 
(unique = true, nullable = false, name = "user 4d” 


public Integer getUserId() { 
return userId; 


Column 
(name = "user_role" 


public Integer getUserRole() { 
return userRole; 

} 

@Column 
(name = "user name", unique = true 
) 
public String getUserName () { 
return userName; 

@Column 
(name = "user pwd" 
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Public String getPassWord() { 
return passWord; 
} 
@Colum 
(name = "user status" 
) 
public Integer getStatus() { 
return status; 
} 
} 


与 测试 集 实体 类 相似 ，@Table 注 解 将 类 对 应 到 atup_user 表 ，@Column 将 类 的 属性 对 应 到 atup_user 表 的 字段 ， 其 中 主键 字段 user_id 根 据 数 据 库 的 sequence 自 增 。 


为 了 方便 查询 ， 我 们 定义 了 JPA 的 名 称 查 询 findByUserName， 根 据 用 户 名 返回 状态 为 正常 的 用 户 数据 ， 定 义 如 下 所 示 。 


QNameqoueries ({ 

@NamedQuery (name = "findByUserName", 

query = "SELECT atupUser FROM AtupUser atupUser 

WHERE atupUser.userName= :userName and atupUser.status=0") 


让 


户 实体 类 对 应 的 数据 表 atup_user 的 DDL 如 下 所 示 。 


CREATE TABLE “atup_user ( 
‘user id” int(11) NOT NULL AUTO INCREMENT, 
“user name ”varchar (255) DEFAULT NULL, 
“user_ pwd varchar (255) DEFAULT NULL, 
‘user role`” int(11) DEFAULT NULL, 
‘user status. int (11) DEFAULT NULL, 
PRIMARY KEY (‘user id )， 
UNIQUE KEY ‘user id (‘user id'`)， 
UNIQUE KEY ‘user name. (‘user name `) 

) ENGINE=InnoDB DEFAULT CHARSET=utf8; 


在 这 段 代 码 中 ， 为 了 简便 ， 我 们 没有 为 用 户 的 权限 和 各 种 状态 单独 建立 表 。 这 里 简 述 如 下 ， 用 户 角色 包括 : 系统 管理 员 (1) 、 作 业 管 理 员 (2) 、 设 备 管理 员 (3) 和 普通 用 户 (4) 。 用 户 状 态 包 括 : 
正常 (0) 和 停 用 (1) 。 详 见 org.feuyeuxjaxrs2.atup.core.constant.AtupParam 接 口 。 


为 了 更 方便 演示 ATUP， 我 们 为 该 表 创 建 初始 用 户 ， 见 表 11-18。 


表 11-18 ATUP 初 始 用 户 列表 


用 户 角色 描述 用 户 名 / 密码 


ATUP 系统 管理 员 atupAdmin/jaxman 
ATUP 作业 管理 员 atupJobKiller/jaxman 
ATUP 设备 管理 员 atupDeviceKeeper/jaxman 
ATUP 普通 用 户 xer/ xer 

表 11-14 对 应 的 数据 库 初 始 化 脚本 如 下 。 


INSERT INTO “jaxrs2 atup'.‘atup user. 

(‘user id', ‘user name‘, user pwd', ‘user role’, ‘user status ) 
VALUES (1,'atupAdmin','650b8lee61374ef758f6e6b8ab68426e',1,0), 
(2, 'atupJobKiller', '650b81lee61374ef758f6e6b8ab68426e' ,2,0), 

(3, 'atupDeviceKeeper', '650b81lee61374ef758f6e6b8ab68426e' ,3,0), 
(4, 

”Xe 

由 

"faa709c5035aea00f9efb278f2ad5df0 

”450) 7 


从 这 段 初始 化 脚本 中 可 以 看 出 ，ATUP 系 统 对 用 户 密码 进行 了 MD5 加 密 。 这 个 处 理 过 程 是 在 atup-page 完 成 的 ， 即 客户 端 加 密 。 使 用 的 算法 来 自 https://github.com/blueimp/Javascript-MD5， 相 关 
脚本 文件 如 下 所 示 。 


https:/ /raw.github.com/blueimp/JavaScript-MD5/master/js/md5.min.js 


(3) 设备 类 设计 


设备 类 定义 了 测试 设备 的 基本 信息 ， 包 括 设备 1D、 主 机 IP、 名 称 、 状 态 和 类 型 ， 此 外 还 有 设备 所 属 用 户 、 添 加 时 间 和 更 新 时 间 。 其 实体 类 代码 片段 如 下 所 示 。 


@Entity 
@Table 
(name = "atup device" 
) 
public class AtupDevice implements Serializable { 
@Id 
Q@GeneratedValue 
(strategy = GenerationType.IDENTITY, generator = "EMP SEQ" 
) 


Q@SequenceGenerator 
(name = "EMP SEQ" 
) 本 


Column 
(unique = true nullable = false, name = "device id" 
) 
Public Integer getDeviceId() { 
return deviceId; 


} 
@ManyToone // 
关注 点 1 
: 设备 和 用 户 的 多 对 一 关系 注解 
QJoinColumn 
(name = "userId" 
) 
public AtupUser getUser() { 
return user; 


QColumn 
(name = "device host", unique = true 


public String getDeviceHost() { 
return deviceHost; 

} 

Column 
(name = "device name", unique = true 


) 


public String getDeviceName () { 
return deviceName; 
} 
@Colummn 
(name = "device status" 
) 
public Integer getDeviceStatus() { 
return deviceStatus; 
} 
@Column 
(name = "device type" 
) 2 
public Integer getDeviceType() { 
return deviceType; 


@Column 
(name = "create time" 


public Date getCreateTime() { 
return createTime; 
} 
@Column 
(name = "update time" 
) 
public Date getUpdateTime() { 
return updateTime; 
} 
} 


与 测试 集 实体 类 类 似 ，@Table 注 解 将 类 对 应 到 atup_device 表 ，@ Column 将 类 的 
户 之 间 的 关系 是 多 对 一 ， 见 关注 点 1。 


为 了 方便 查询 ， 我 们 定义 了 JPA 的 名 称 查 询 findByDevicelp 和 findDevicesByUser， 分 别 根据 设备 主机 IP 和 名 称 返 


属性 对 应 到 atup_device 表 的 字段 ， 其 


回 


该 表 的 数据 集 ， 定 义 如 下 所 示 。 


上 键 字段 device_ id 根据 数据库 的 sequence 自 


增 。 额 外 要 说 明 的 是 ， 设 备 和 | 


@NamedQueries ({ 

@NamedQuery (name = "findByDeviceIp", 

query = "SELECT atupDevice FROM AtupDevice atupDevice 
WHERE atupDevice.deviceHost= :deviceHost"), 
@NamedQuery (name = "findDevicesByUser", 

query = "SELECT atupDevice FROM AtupDevice atupDevice 
WHERE atupDevice.user.userId= :userId")}) 


设备 实体 类 对 应 的 数据 表 atup_device 的 DDL 如 下 所 示 。 


CREATE TABLE ‘atup device. ( 
‘device idq” int (I1) NOT NULL AUTO_INCREMENT, 
‘device host ”varchar (255) DEFAULT NULL, 
‘device name. varchar (255) DEFAULT NULL, 
‘device type. int(11) DEFAULT NULL, 
‘device status、 int (11) DEFAULT NULL, 
“userId ”int(11) DEFAULT NULL, 
‘create time ”datetime DEFAULT NULL, 
‘update _ time ”datetime DEFAULT NULL, 
PRIMARY KEY (‘device id), 
UNIQUE KEY ‘device id (‘device id’), 
UNIQUE KEY ‘device host. (‘device host') 
UNIQUE KEY ‘device name” (‘device name) 
KEY ‘FK atup device userId. (‘userId'), 


1 
1 


CONSTRAINT “ atup device userId ”FOREIGN KEY (userId `) 


REFERENCES “atuPp_user 


(‘user id ) 


SANITY 测 试 、 回 归 测 试 等 涡 


在 这 段 代 码 中 ， 设 备 状态 字段 device_status 的 值 包括 : 空闲 ( 


0) 、 忙 碌 (1) 和 宕 机 (2) ， 设 备 类 


试 时 间 不 是 很 长 的 测试 ， 慢 速 测试 主 


(4) 测试 结果 设计 


型 字段 device type 的 值 包括 : 快速 测试 (1) 和 慢 速 测试 (2) 。 快 速 测试 主 


包括 冒 烟 测试 、 


包括 性 能 测试 、 系 统 测试 等 全 面 或 者 耗 时 的 测试 。 详 情 可 参见 org.feuyeuxjaxrs2.atup.core.constant.AtupParam 接 口 。 


测试 结果 是 测试 作业 根据 测试 


例 在 指定 设备 上 运行 的 测试 结果 ， 包 括 如 下 最 简 信息 : 测试 结果 ID、 内 容 、 状 态 、 测 试 


例 、 测 试 者 、 测 试 设备 ， 以 及 4 


成 时 间 和 更 新 时 间 。 其 实体 类 代码 片段 如 下 所 


Q@Entity 
@Table 
(name = 
) 
public class AtupTestResult implements Serializable { 
@Id 
Q@GeneratedValue 
(strategy = GenerationType.IDENTITY, generator = 
) 


"test result" 


Q@SequenceGenerator 
(name = "EMP SEQ" 
) 入 

@Column 
(unique = true, nullable = false, name = "result id" 
) 
public Integer getResultId() { 
return resultId; 


} 
Q@ManyToone // 


关注 点 1: 

测试 结果 和 测试 用 例 的 多 对 一 注解 
Q@JoinColumn 

(name = "caseId" 


public AtupTestCase getTestCase() { 
return testCase; 


} 
@ManyToone// 


关注 点 2: 

测试 结果 和 用 户 的 多 对 一 注解 
Q@JoinColumn 

(name = "userId" 

) 

public AtupUser getUser() { 

return user; 


Column 
(name = "result_ status" 


public Integer getResultStatus() { 
return resultStatus7 
} 
@Column 
(name = "result body" 
) 
public String getResultBody() { 
return resultBody; 
} 
@Colummn 
(name = "create time" 
) 
public Date getCreateTime() { 


"EMP_SEQ" 


return createTime; 
} 
@Columm 
(name = "update time" 
) 
public Date getUpdateTime() { 
return updateTime; 


} 
@ManyToOne// 

关注 点 3 

: 测试 结果 和 测试 设备 的 多 对 一 注解 
Q@JoinColumn 

(name = "deviceId" 


) 
Public AtupDevice getDevice () { 
return device; 
} 
i 


在 这 段 代 码 中 ，@Table 注 解 将 类 对 应 到 test_result 表 ，@ Column 将 类 的 属性 对 应 到 test_result 表 的 字段 ， 其 中 主键 字段 result_id 根 据 数 扫 


的 关系 都 是 多 对 一 ， 见 关注 点 1~ 关 注 点 3。 


为 了 方便 查询 ， 我 们 定义 了 JPA 的 名 称 查询 findResultByTestCase、findResultByStatus 和 findResultByUser， 分 别 根 据 测试 


居 库 的 sequence 


例 、 疯 


增 。 测 试 结果 和 测试 


例 、 设 备 、 


上 


试 结果 状态 和 测试 者 返回 该 表 的 数据 集 ， 


定义 如 下 所 示 。 


户 之 间 


QNamedoueries ({ 

@NamedQuery (name = "findResultByTestCase", 

query = "SELECT testResult FROM AtupTestResult testResult 
WHERE testResult.testCase= :testCase"), 

@NamedQuery (name = "findResultByStatus", 

query = "SELECT testResult FROM AtupTestResult testResult 
WHERE testResult.resultStatus= :resultStatus"), 
@NamedQuery (name = "findResultByUser", 

query = "SELECT testResult FROM AtupTestResult testResult 
WHERE testResult.user.userId= :userId")}) 


测试 结果 实体 类 对 应 的 数据 表 test_result 的 DDL 如 下 所 示 。 


CREATE TABLE “test_result 
( 
‘result id. int 
(11 咯 
) NOT NULL AUTO INCREMENT, 
‘result body. varchar 
(255 区 
) DEFAULT NULL, 
‘result status. int 
(11 
) DEFAULT NULL, 
“caseId” int 
加 
) DEFAULT NULL, 
‘deviceId. int 
(11 
) DEFAULT NULL, 
“userId” int 
C11 
) DEFAULT NULL, 
‘create time’ datetime DEFAULT NULL, 
‘update time ”datetime DEFAULT NULL, 
PRIMARY KEY 
(result id. 
) ， 
UNIQUE KEY ‘result id. 
(“result id、 
) ， 
KEY ‘FK test result caseId. 
(“caseId. 


’ 
KEY “FK test result userId. 
(“userId. 


’ 
KEY ‘FK test result deviceld. 
(deviceId 
) ， 
CONSTRAINT “FK_test_result_caseId ”FOREIGN KEY 
(“caseId. 
) 
REFERENCES 
(case id 


“test_case 


) ， 
CONSTRAINT 
(“deviceId. 
) 
REFERENCES 
(device id. 


‘FK test _ result deviceId’ FOREIGN KEY 


‘atup_device. 


和 
CONSTRAINT 


“FK test_ result userId FOREIGN KEY 
(“userId. 


REFERENCES 


‘atup_user. 
(user id 


) 
) ENGINE=InnoDB DEFAULT CHARSET=utf87 


在 这 段 代 码 中 ， 测 试 结果 状态 字段 result_status 包 括 : 成 功 (0) 、 失 败 (1) 和 未 知 错误 (2) ， 详 情 可 参见 org.feuyeux.jaxrs2.atup.core.constant.AtupParam 接 口 。 


(5) 数据 源 配置 


JPA 数 据 源 的 配置 根据 事务 类 型 transactionType 的 不 同 分 为 RESOURCE_LOCAL 和 JTA 两 种 方式 。 


全 阅读 指南 “本章 使 用 的 JPA 实 现 是 EclipseLink， 有 关 配 置 的 详细 信息 可 参考 如 下 地 址 。 


JPA 配 置 列 表 : http://wiki.eclipse.org/EclipseLink/Examples/JPA。 


Tomcat 容 器 配置 : http://wiki.eclipse.org/EclipseLink/Examples/JPA/Tomcat_Web_Tutorial。 


EclipseLink 缓 存 配置 : http://wiki.eclipse.org/EclipseLink/Examples/JPA/Caching。 


RESOURCE_LOCAL 实 例如 下 ， 配 置 文 件 src/main/resources/META-INF/persistence.xml 中 包括 实体 类 列表 和 数据 源 信息 。 


<persistence-unit name="jpaMysql2" transaction-type="RESOURCE LOCAL"> 
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> 


<class>org. feuyeux.jaxrs2.atup.core.domain.AtupDevice</class> 
<class>org.feuyeux.jaxrs2.atup.core.domain.AtupTestCase</class> 


<class>org.feuyeux.jaxrs2.atup.core.domain.AtupTestResult</class> 
<class>org. feuyeux.jaxrs2.atup.core.domain.AtupTestSuite</class> 


<class>org. feuyeux.jaxrs2.atup.core.domain.AtupUser</class> 


<properties> 


<property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver" /> 
<property name="javax.persistence.jdbc.url" 
value="jdbc:mysql://localhost:3306/jaxrs2 atup" /> 
<property name="javax.persistence.jdbc.user" value="root" /> 
<property name="javax.persistence.jdbc.password" value="root" /> 
<property name="eclipselink.ddl-generation" value="create-tables" /> 
</properties> 

</persistence-unit> 


咱 A 实例 如 下 ， 配 置 文 件 src/main/resources/META-INF/persistence.xml 中 包括 实体 类 列表 ， 其 数 提 


是 容器 级 别 的 。 本 章 使 用 Tomcat 作 为 容器 ， 可 参见 11.2.1 节 。 


<persistence-unit name="jpaMysql" transaction-type="JTA"> 
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> 
<jta-data-source>java:/comp/env/jdbc/AtupDataSource</jta-data-source> 
<non-jta-data-source>java:/comp/env/jdbc/AtupDataSource</non-jta-data-source> 
<class>org. feuyeux.jaxrs2.atup.core.domain.AtupDevice</class> 
<class>org.feuyeux.jaxrs2.atup.core.domain.AtupTestCase</class> 
<class>org.feuyeux.jaxrs2.atup.core.domain.AtupTestResult</class> 
<class>org. feuyeux.jaxrs2.atup.core.domain.AtupTestSuite</class> 
<class>org. feuyeux.jaxrs2.atup.core.domain.AtupUser</class> 
<properties> 

<property name="eclipselink. 

</properties> 

</persistence-unit> 


ddl-generation" value="create-tables" /> 


(6) Ubuntu 系 统 下 MySQL 简 明 参 考 


这 里 以 Ubuntu 系统 下 的 MySQL 的 安装 和 配置 作为 示例 。 如 果 服 务 器 存在 旧版 本 ， 那 么 可 以 先 使 


如 下 命令 卸载 旧版 本 。 


sudo apt-get remove --purge mysql-server mysql-client mysql-common 
sudo apt-get autoremove 
sudo apt-get autoclean 


使 用 wget 下 载 64 位 Debian 安 装 包 。 


wget http://cdn.mysql.com/Downloads/MySQL-5.6/mysql-5.6.15-debian6.0-x86_64.deb 


安装 Debian 安 装 包 命令 如 下 。 注 意 ， 其 默认 安装 路 径 是 /opt/mysql/。 


sudo apt-get install libaio-dev 
sudo dpkg -i mysql-5.6.15-debian6.0-x86_ 64.deb 


安装 完毕 后 ， 可 参考 如 下 步骤 配置 MySQL 服 务 器 ， 详 细 信 息 可 参考 : http://dev.mysql.com/doc/refman/5.6/en/binary-installation.html。 


sudo groupadd mysql 

sudo useradd -r -g mysql mysql 

cd /opt/mysql/server-5.6/ 

sudo mkdir data 

sudo chown mysql:mysql data 

sudo mkdir log 

sudo chown mysql:mysql log 

sudo cp /opt/mysql/server-5.6/share/english/errmsg.sys /usr/share/mysql/errmsg.sys 
sudo chown mysql:mysql /usr/share/mysql/errmsg.sys 

sudo scripts/mysql install db --user=mysql --no-defaults 

sudo cp support-files/my-default.cnf /etc/mysql/my.cnf 

sudo cp support-files/mysql.server /etc/init.d/mysql.server 

sudo cp support-files/mysql-log-rotate /etc/logrotate.d/mysql.server 


完成 上 述 配置 后 ， 使 用 “sudo nano/etc/mysql/my.cnf” 命 令 开始 对 配置 文件 进行 编辑 ， 参 考 配置 如 下 所 示 。 


[client] 

port = 3306 

socket = /tmp/mysql56.sock 
[mysqld_ safe] 

port = 3306 

socket = /tmp/mysq156.sock 
nice =0 

[mysqld] 

user = mysql 

pid-file = /tmp/mysql56.pid 
port = 3306 

socket = /tmp/mysql56.sock 
basedir = /opt/mysql/server-5.6 
datadir = /opt/mysql/server-5.6/data 
tmpdir = /tmp 

lc-messages-dir = /usr/share/mysql 


12750.051 
16M 
16M 


#bind-address = 
key_buffer 
max allowed packet 


thread stack 192K 
thread cache size 8 
myisam-recover = BACKUP 
query cache limit = 1M 
query cache size = 16M 


lo0g error= /cpt/mysql/server-5.6/1og/error.1og 
expire logs days = 10 

max binlog size 
[mysqldump] 
quick 
quote-names 
max allowed packet i 
[mysql] 

#no-auto-rehash # faster start of mysql but no tab completition 
[isamchk] 

key buffer = 16M 

sql_ mode=NO_ENGINE SUBSTITUTION 1 STRICT_TRANS_ TABLES 


100M 


16M 


最 后 ， 启 动 MySQL 服 务 ， 并 登录 验证 。 


sudo service mysql.server start 
mysqladmin -u root password 
‘root 
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2 数据 库 访 问 层 


设计 好 数据 库 并 配置 好 连接 后 ， 接 下 来 的 工作 是 对 数据 库 的 访问 。 我 们 分 别 讲述 通 


(1) AtupDao 类 


访问 类 和 一 个 具体 的 访问 类 ， 以 示 说 明 。 


AtupDao 类 是 ATUP 系 统 的 通用 数据 库 访问 层 类 ， 因 此 其 命名 中 接收 一 个 泛 型 ， 示 例 代 码 如 下 所 示 。 


Package org.feuyeux.jaxrs2.atup.core.dao; 


关注 点 1 

: 泛 型 定义 

public class AtupDao<T> { 
a 


关 
: 日 志 实 例 
Private final Logger 10g = LogManager.getLogger 
(AtupDao.class .getName () 
@PersistenceContext 
EntityManager entityManager;// 
关注 点 3 
: 实体 管理 类 实例 
Private Class<T> entityClass; // 
注 皮 4 


关注 点 
: 特 化 实体 类 的 类 型 
QSuppressWarnings 
("unchecked" 
) 
public AtupDao() { 
final Type genericSuperclass = getClass () .getGenericSuperclass () 7 
二 
(genericSuperclass instanceof ParameterizedType 
{ 
final ParameterizedType parameterizedType = 
(ParameterizedType 
) genericSuperclass; 
final Type[] actualTypeArguments = parameterizedType.getActualTypeArguments () 7 
this .entityClass = 
(Class<T> 
) actualTypeArguments[0]; 
} 
} 


在 这 段 代码 中 ， 泛 型 T 的 特 化 使 用 上 文 提 到 的 5 个 实体 类 ， 见 关注 点 1。AtupDao 类 包含 3 个 属性 ， 第 一 个 属性 是 日 志 类 实例 ， 见 关注 点 2，ATUP 全 局 使 用 了 Log4j 2 作为 日 志 记录 工具 ， 可 参考 下 文 相 关 
内 容 ; 第 二 个 属性 是 实体 管理 类 实例 ， 见 关注 点 3， 类 似 Hibernate 的 Session 实 例 ， 该 属性 使 用 @PersistenceContext 注 解 ， 表 示 该 实例 是 一 个 持久 化 上 下 文 ， 由 容器 管理 。 容 器 提供 
EntityManagerFactory 的 实例 来 维护 这 个 属性 的 生命 周期 ; 第 三 个 属性 是 指定 特 化 的 实体 类 类 型 ， 见 关注 点 4， 在 构造 子 中 通过 反射 机 制 动 态 地 为 其 赋值 。 这 个 属性 的 作用 是 为 查询 提供 特 化 类 型 参数 。 


AtupDao 类 为 子 类 提供 了 通用 的 数据 库 访 问 实现 ， 比 如 分 页 查询 、 插 入 、 更 新 、 删 除 等 通用 操作 ， 示 例 代 码 片段 如 下 所 示 。 


private List<T> findAll 
(final boolean isPaging, final int firstResult, 
final int maxResults 
2 
final CriteriaBuilder cb = entityManager.getCriteriaBuilder(); 
final CriteriaQuery<T> cq = cb.createQuery 
(entityClass 
); 
final TypedQuery<T> q = entityManager.createQuery 
《ed 
) 
(isPaging 
) { 
q.setMaxResults 
(maxResults 
q.setFirstResult 
(firstResult 
); 
} 
return q.getResultList (); 
} 


@Transactional // 
关注 点 1 
: 容器 管理 事务 注解 
Public T save 
(final T entity 
) { 


entityManager.persist 
(entity 


注 点 2 
: 为 调用 者 提供 插入 后 的 实体 类 实例 
entityManager.flush () 7 
return entity; 


} 


在 这 段 代 码 中 ， 写 操作 使 用 了 @Transactional 注 解 ， 表 示 该 方法 执行 事务 提交 ， 见 关注 点 1。 


JPA 的 插入 接口 没有 返回 值 ， 这 对 于 REST 接 口 为 客户 端 提供 返回 值 来 说 ， 非 常 不 方便 。 一 个 变通 的 做 法 是 使 用 EntityManager 的 flush0) 方 法 更 新 内 存 中 的 实体 类 实例 ， 然 后 将 其 返 
实例 已 经 包含 数据 库 为 之 生成 的 主键 信息 ， 见 关注 点 2。 


回 


。 此 时 ， 该 实体 类 


宅 人 坑 事 


将 @Transactional 注 解 标 记 在 数据 访问 层 的 这 种 处 理 是 很 有 争议 的 ， 因 为 一 个 业务 层 的 原子 操作 通常 不 止 一 张 表 的 一 次 写 操作 ， 如 果 是 这 样 ， 那 么 这 个 @Transactional 注 解 应 当 标记 在 业务 层 的 相关 方法 
上 。 但 是 ， 在 能 确保 该 操作 在 业务 中 为 原子 操作 的 前 提 下 ， 本 例 的 这 种 做 法 有 其 细 粒 度 的 优势 。 


(2) AtupDeviceDao 类 


AtupDao 的 子 类 分 别 对 应 一 个 实体 类 ， 子 类 之 间 的 关系 是 平 级 的 。 这 里 以 设备 访问 类 AtupDeviceDao 为 例 ， 其 他 子 类 的 实现 类 似 。 该 类 集成 了 AtupDao 并 提供 泛 型 的 特 化 类 型 为 AtupDevice。 示 例 代 
码 如 下 所 示 。 


@Repository // 

关注 点 1 

: Spring 

数据 访问 层 组 件 注解 

public class AtupDeviceDao extends AtupDao<AtupDevice> { 


// 
关注 点 2 
: 按 用 户 查询 设备 列表 
public List<AtupDevice> findDevicesByUser 
(final Integer userId 
} 4 
return entityManager.createNamedQuery 
("findDevicesByUser", 
AtupDevice.class 
) .setParameter 
("userId", userId 
) .getResultList (); 
} 


在 这 段 代 码 中 ，AtupDeviceDao 类 使 用 了 @Repository 注 解 ， 表 示 该 类 是 Spring 的 组 件 类 ， 其 实例 由 Spring 容器 管理 ， 见 关注 点 1。 


对 于 实体 类 特殊 的 访问 方法 ， 定 义 在 AtupDao 的 子 类 中 。 这 里 以 JPA 名 称 查询 findDevicesByUser 为 例 ， 在 AtupDeviceDao 中 , 定义 了 findDevicesByUser() 方 法 ， 见 关注 点 2。 该 方法 调用 
EntityManager 的 createNamedQuery() 方 法 创建 一 个 名 称 查询 ， 参 数 是 AtupDevice 中 定义 的 名 称 查询 名 称 findDevicesByUser 和 AtupDevice 类 型 。findDevicesByUser 接 收 的 参数 信息 是 用 户 ID， 最 后 调 
查询 接口 的 getResultList() 方 法 返回 结果 集 。 


3. 日 志 记录 


ATUP 模 块 使 用 开源 日 志 工 具 Log4j 的 增强 版 本 Log4j 2， 这 个 版 本 采用 异步 MO， 增 强 了 吞吐 能 力 ， 详 见 其 官方 网 站 : http://logging.apache.org/log4j/2.x/。 其 默认 配置 文件 的 路 径 和 名 称 是 : 
src\main\resources\log4j2.xml， 示 例如 下 。 


<?xml Version="1.0" encoding="UTF-8"?> 
<Configuration status="off"> 
<Appenders> // 

关注 点 1 

: Appender 

的 配置 

// 

关注 点 2 

: 日 志 输 出 路 径 

<File name="file" fileName="${sys:user.home}/atup log/atup case.10og"> 

<PatternLayout> 加 二 
<Pattern>%d %p sc{f1.} [St] Sm g%exgsn</Pattern>// 

关注 点 3 


: 日 志 输 出 格式 
</PatternLayout> 
</File> 
<Console name="STDOUT" target="SYSTEM OUT"> 
<PatternLayout pattern="%c{1.} %msn"/> 
</Console> 
</Appenders> 
<Loggers> 
<Root level="DEBUG"> // 
关注 点 4 
: 日 志 输 出 级 别 
<AppenderRef ref="file" level="DEBUG"/> 
<AppenderRef ref="STDOUT" level="DEBUG"/> 
</Root> 
</Loggers> 
</Configuration> 


在 这 段 代 码 中 ，ATUP 开 发 中 使 用 了 两 个 Appender， 分别 输出 日 志 到 文件 和 控制 台 ， 见 关注 点 1。 动 态 变 量 $fsys:user.home} 指 向 用 户 根 目录 ， 见 关注 点 2。 对 于 Windows 平 台 ， 示 例如 
Ci\Users\Administrator， 对 于 Ubuntu 等 Linux 平 台 ， 示 例如 /home/eric。 日 志 输 出 格式 见 关注 点 3。 在 匹配 模式 参数 中 ，%d 为 日 期 ，%p 为 日 志 级 别 ，%c 为 类 名 ， 数 字 指 定 打印 类 名 长 度 ，%t 为 线 
程 ，%ex 是 异常 ，%n 是 换行 标记 ，%m 是 日 志 信 息 。 输 出 级 别 是 DEBUG， 见 关注 点 4。 


4.Spring 配 置 


上 述 的 数据 库 访 问 层 已 经 用 到 Spring 的 配置 ， 这 里 简 述 如 下 。ATUP 模 块 使 用 Spring 的 默认 配置 文件 路 径 和 名 称 : src/main/resources/applicationContext.xml。 示 例 代码 如 下 。 


六 
关注 点 1 
: 自动 扫描 并 加 载 的 类 所 在 包 定 义 
<context :component-scan base-package="org.feuyeux.jaxrs2.atup"/> 
<!-- JPA Transaction manager JPA --> 
<bean id="entityManagerFactory" 
Class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean"> 
// 
关注 点 2 . 
: 实体 管理 工厂 和 持久 化 单元 定义 
<property name="persistenceUnitName" value="jpaMysql"/></bean> 
<!-- TransAction Manager JPA --> 
<bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager"> 


: 事务 管理 和 实体 管理 工厂 定义 
<property name="entityManagerFactory" ref="entityManagerFactory"/></bean> 


在 这 段 代 码 中 ， 关 注 点 1 定义 了 容器 扫描 ， 并 自动 加 载 其 中 的 类 的 所 属 包 名 org.feuyeux.jaxrs2.atup。 关 注 点 2 定义 了 实体 管理 工厂 接口 EntityManagerFactory 实 例 ， 使 用 的 持久 层 配 置 是 jpaMysql， 
该 配置 参见 前 述 的 数据 库 配 置 。 关 注 点 3 是 配置 事务 管理 实例 TransactionManager， 使 EntityManagerFactory 实 例 生 产 的 EntityManager 接 受 容器 级 的 事务 的 管理 。 关 注 点 4 启用 注解 方式 的 事务 管理 配 
置 。 


5. 封 装 REST 客 户 端 


REST 客 户 端 的 封装 是 为 了 满足 ATUP 模 块 之 间 的 访问 以 及 静态 页 面 对 ATUP 模 块 提供 的 REST 服 务 的 访问 。 其 中 ， 服 务 器 端 模块 之 间 的 访问 封装 在 核心 模块 atup-core 的 AtupRequest 类 中 ， 页 面 的 访问 
封装 在 通用 脚本 文件 atupRest 中 。 


(1) 核心 模块 atup-core 


AtupRequest 类 是 客户 端 发 起 REST 请 求 的 封装 类 ， 包 括 对 使 用 各 种 HTTP 通 用 方法 的 封装 、 连 接 器 和 连接 配置 的 封装 等 ， 示 例 代 码 片段 如 下 。 


Public class AtupRequest<R, E> {// 
关注 点 1 
: 请 求 包装 类 的 泛 型 定义 
Public AtupRequest() { 
} 


public AtupRequest 
(final ClientConfig clientConfig 
) { 
this.clientConfig = clientConfig; 
} 
public void setClientRegisters 
(final Set<Class<?>> clientRegisters 
) { 


this.clientRegisters = clientRegisters; 


} 
public void proxy 
(String proxyUri, String proxyUserName, String proxyPassword 
{ 

if 

(this.clientConfig == null 

) { 

this.clientConfig = new ClientConfig(); 

} 
this.clientConfig.property 


(ClientProperties.PROXY URI, proxyUri 
3 本 
this.clientConfig.property 
(ClientProperties.PROXY USERNAME, proxyUserName 
) ; 本 
this.clientConfig.property 
(ClientProperties.PROXY PASSWORD, proxyPassword 
) 7 
//timeout 
public void timeout 
(int connectTimeout, int readTimeout 
) { 
本 
(this.clientConfig == null 
) { 


this.clientConfig = new ClientConfig(); 


b: 
if 
(connectTimeout > 0 
) { 
this.clientConfig.property 
(ClientProperties. CONNECT TIMEOUT, connectTimeout 
); 
} 
村 
(readTimeout > 0 
) { 
this.clientConfig.property 
(ClientProperties. READ TIMEOUT, readTimeout 
); 
} 


宅 人 坑 事 


lientProperties.CONNECT_TIMEOUT 和 ClientProperties.READ_TIMEOUT 两 个 属性 接收 的 参数 必须 可 以 转化 为 Integer 类 型 。 默 认 值 是 09， 代表 无 限期 ， 单 位 是 毫秒 。 


在 这 段 代码 中 ，AtupRequest 定 义 了 两 个 泛 型 参数 : R 和 E， 分 别 是 返回 值 类 型 和 请 求实 体 类 型 ， 见 关注 点 1。 该 类 主要 处 理 两 件 导 
clientRegisters 的 赋值 。 前 者 包括 安全 、 超 时 等 参数 ， 后 者 包括 Provider 和 资源 类 等 注册 类 信息 。 第 二 是 将 配置 参数 赋值 给 Client 实 例 


情 ， 第 一 是 封装 客户 端 配置 参数 ， 主 要 包括 对 ClientConfig 实 例 和 


， 并 处 理 请 求 方法 和 请 求 参数 。 


如 下 面 代码 片段 所 示 ， 请 求 参数 分 别 是 请 求 方法 名 称 、 请 求 资源 地 址 、 请 求 头 参数 集合 、 请 求 参数 集合 、 请 求 媒 体 类 型 、 请 求实 体 和 返回 类 型 。 


public E rest 
(final String method, final String requestUrl, 


final Set<AtupRequestParam> headParams, final Set<AtupRequestParam> queryParams, 
final MediaType requestDataType, final R requestData, final Class<E> returnType 


) 泛 
二 
(clientConfig 一 null 
4 
clientConfig = new ClientConfig(); 
} 
final Client client = ClientBuilder.newClient 
(clientConfig 
) 7 
4 
(!CollectionUtils.isEmpty 
(clientRegisters 
7 苹 
for 
(final Class<?> clazz : clientRegisters 
) { 
client .register 
(clazz 
: 
WebTarget webTarget = client.target 
(requestUrl 


2 
〈!CollectionUtils.isEmpty 
(queryParams 

)) 1 


for 


(final AtupRequestParam atupRequestParam : queryParams 


) { 
webTarget = webTarget .queryParam 
(atupRequestParam.getKey (), 
atupRequestParam.getValue () 
} 
下 


final Invocation.Builder invocationBuilder = webTarget.request (); 


车 在 
(!CollectionUtils.isEmpty 
(headParams 
)) { 


for 


(final AtupRequestParam atupRequestParam : headParams 


) { 
invocationBuilder.header 
(atupRequestParam.getKey (), 
atupRequestParam.getValue () 
i 
} 
} 
javax.ws.rs.core.Response response = null; 
Entity<R> entity; 


switch 
(method 
大 到 
case GET: 
response = invocationBuilder.get () 7 
break; 


case DELETE: 
response = invocationBuilder.delete(); 
break; 
case PUT: 
entity = Entity.entity 
(requestData, requestDataType 
response = invocationBuilder.put 
(entity 
break; 
case POST: 
entity = Entity.entity 
(requestData, requestDataType 


response = invocationBuilder.post 


(entity 

break; 
上 
(response != null 


) { 


return response.readEntity 


(returnType 
) 3; 
} else { 
return null; 
} 


(2) 通用 脚本 atupRest 


atupRest.js 封 装 了 浏览 器 端 请 求 REST 资 源 地 址 的 函数 ， 代 码 片 段 如 下 所 示 。 


function restGet 


(restUrl, httpMethod, callback 


) { 


rest 


(restUrl, httpMethod, "", "application/json", "json", callback 


} 


function restSet 


(restUrl, httpMethod, entity, callback 


sa 


rest 


function rest 


(restUrl, httpMethod, entity, "application/json", "json", callback 


(restUrl, httpMethod, entity, contentType, dataType, callback 


) { 
var resultLine = jQuery 
('#resultDiv' 
; 
resultLine.html 
(LOADING 
de 
关注 点 2 
: 设 定 为 加 载 状态 


Var UserId = storage.getItem 


("userId" 
) i// 
关注 点 3 
: HTML5 
的 Storage 


吾 忌 ， 


Var userRole = Storage .getItem 


("userRole" 
> 
Var request = jQuery.ajax 


({type: httpMethod, url: restUrl, 
headers: {'Atup-User': userId, 'Atup-UserRole': userRole}, 
data: entity, contentType: contentType, dataType: dataType, 


crossDomain: true} 


// 
关注 点 4 
: 成 功 的 回调 
request .done 
(function 
(data 
7 
try { 
if 


(data === null || data === undefined 


j 


resultLine.html 


(NO_RESULT 
34 


关注 点 5 
: 设 定 为 无 结果 状态 


} else if 


(data.statusCode && data.statusCode != normal status 


时 


resultLine.html 


("Error:" + data.errorInfo 
Fa 
关注 点 6 
: 设 定 为 错误 状态 

} else if 
(callback != null 


resultLine.html 


callback 


resultLine.html 


(e 
) ;2// 
关注 点 8 
: 输出 错误 信息 
} 


} 
); 
a/ 
关注 点 9 
: 失败 的 回调 
request .fail 
(function 
(textStatus, errorThrown 
兴 交 

resultLine .html 


(errorThrown + " status=" + textStatus .status + " text=" + 


textStatus.statusText 

); 

} 
2 

resultLine.append 
(" DONE!" 
) 2// 
关注 点 10 
: 设 定 为 完成 状态 
} 


在 这 段 代码 中 ， 方 法 的 参数 分 别 是 REST 资 源 地 址 、 请 求 方法 名 称 、 请 求实 体 、 请 求 头 contentType 类 型 、 返 


ATUP 的 纯 HTML 页 面 上 都 包含 一 


AAA， 
个 命 


回 


回 


值 类 型 和 


调 函 数 ， 见 关注 点 1。 


名 为 resultDiv 的 DIV 标签 ， 用 于 动态 显示 REST 请 求 的 处 理 进程 ， 在 请 求 


显示 异常 信息 ， 分 别 见 关注 点 2、 关 注 点 5~ 关 注 点 8 和 关注 点 10。 


请 求 头 包含 HTML5 的 storage 保 存 的 当前 用 户 ID 和 用 户 角 色 ， 见 关注 点 3， 这 部 分 在 下 文 阐述 。 


始 之 前 显示 为 “loading…” ， 请 求 处 理 结束 后 显示 为 “DONE! ” ， 发 生 异 常情 况 时 ， 


请 求 是 通过 jQuery 的 ajax() 函 数 实 现 的 ， 需 要 额外 说 明 的 是 ，ATUP 各 模块 独立 部 署 ， 因 此 需要 设置 跨 域 请 求 值 crossDomain 为 true。ajax() 函 数 提供 了 两 个 回调 方法 一 一 done(0 和 fail0， 分 别 用 于 处 理 
请 求 成 功 和 请 求 异常 ， 见 关注 点 4 和 关注 点 9。 后 者 的 处 理 是 将 错误 信息 显示 在 resultDiv 上 ， 前 者 要 判断 服务 器 端的 处 理 是 否 有 返回 值 ， 如 果 没有 ，data 为 空 ， 将 没有 返回 值 这 一 信息 显示 在 resultDiv 上 ; 如 
果 正 常 处 理 中 包含 错误 代码 (statusCode) ， 处 理 同 异 常情 况 ; 否则 调用 参数 中 的 回调 函数 。 


调用 atupRestjs 封 装 的 函数 是 HTML 页 面 处 理 REST 请 求 的 唯一 方式 ， 这 保证 了 统一 的 代码 风格 和 处 理 方式 ， 对 安全 、 性 能 等 环节 做 到 了 统一 管理 。 这 里 给 出 一 个 调用 示例 ， 示 例 代 码 如 下 所 示 。 


function updateUser() { 

Var userName = jQuery.trim 
(jQuery 
("#userName" 
) .val() 
i 

Var password = jQuery 
("#password" 
) .val(); 

Var hashPassword = md5 
(password 

Var userRole = jQuery 
("#role" 
) .val(); 

var putData = JSON.stringify 
( 

{userName: userName, passWord: hashPassword, userRole: userRole} 


restSet 
(HOST + ATUP USER BASE URI + USER PATH, PUT METHOD, putData, renderUpdate 
站 加 加 四 
} 
function renderUpdate 
(gata 
和 
jQuery 
("#usersDiv" 
) .html 
k 
<div><span style='width:100px;display:inline-block; '>User ID</span>" 
); 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
jQuery 
("#usersDiv" 
) .append 
(gata.userId 
) 3; 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
jQuery 
("#usersDiv" 
) .append 
(gata.userName 
) 3; 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
jQuery 
("#usersDiv" 
) .append 
("</span></div>" 


} 


在 这 段 代 码 中 ， 更 新 用 户 信息 的 REST 请 求 调 用 了 封装 的 方法 restSet()， 并 提供 回调 函数 renderUpdate()。updateUser() 方 法 首先 从 页 面 收集 用 户 信息 ， 然 后 将 其 转换 为 JSON 格 式 的 数据 并 调 
atupRestjjs 中 的 rest() 方 法 ， 回 调 函 数 renderUpdate( 用 于 在 页 面 上 更 新 处 理 结果 信息 。 


6 .测试 作业 分 派 


测试 作业 的 创建 过 程 可 以 理解 为 当前 用 户 根据 测试 用 例 选 择 测试 设备 并 提交 到 系统 ， 系 统 将 其 排队 的 过 程 。 测 试 作业 的 下 发 过 程 可 以 理解 为 系统 根据 优先 级 提取 排队 作业 ， 如 果 其 运行 测试 的 设备 状态 
空闲 ， 即 下 发 该 作业 ， 否 则 放弃 出 队 操 作 。 测 试 作业 的 下 发 可 以 并 行 执行 。 


前 述 的 用 户 故 事 中 定义 了 3 种 类 型 的 作业 。 作 为 演示 ， 本 例 所 示 的 测试 作业 只 涉及 用 户 手动 创建 、 系 统 排队 即时 下 发 的 作业 ， 没 有 涉及 系统 周期 自动 创建 作业 和 系统 定时 下 发 作业 。 


(1) 设备 资源 探测 


如 前 所 述 ， 设 备 的 状态 包括 : 空闲 (0) 、 忙 委 (1) 和 死机 (2) 。 只 有 其 处 于 空闲 时 ， 才 可 以 接收 新 的 测试 作业 。 因 此 ， 首 先 演示 设备 探测 的 处 理 。 测 试探 测 结果 和 下 发 时 对 设备 状态 的 查询 这 一 写 
一 读 两 个 线程 使 用 数据 库 来 同步 。 


设备 探测 是 周期 性 的 动作 ， 可 以 使 用 系统 的 Crontab 周 期 地 触发 cURL 脚 本 来 实现 ，cURL 访 问 一 个 一 次 性 更 新 设备 状态 的 REsT 资 源 地 址 。 该 资源 地 址 也 可 以 通过 Spring 配置 的 Quartz 工 具 来 调用 。 


上 


另 一 种 方式 是 通过 编码 完成 周期 性 的 动作 ， 并 公布 其 资源 地 址 。 可 以 在 系统 启动 时 触发 ， 也 可 以 由 外 部 调用 cURL 脚本 来 触发 。 


本 例 使 用 后 一 种 方式 ， 示 例 代码 如 下 ， 参 考 类 为 org.feuyeux.jaxrs2.atup.device.service.StationDetectService。 


detectTask.scheduleWithFixedDelay 
(new Runnable() {// 
关注 点 1 
: 定义 周期 性 执行 线程 
Override 
public void run() { 
try { 
List<AtupDevice> deviceList = dao.findAll (); 
for 
(final AtupDevice atupDevice : deviceList 
// 


) 


关注 点 2 

: 遍历 并 探测 设备 
final String detectPath = AtupApi.PROTOCOL + 
atupDevice.getDeviceHost() + ":" + 
AtupApi .SERVICE PORT + AtupApi .SERVICE PATH; 
final AtupRequest<String, Integer> request = new AtupRequest<>(); 
Ni 


注 点 3 
: 请 求 超时 设置 
est .timeout 


(AtupVariable.DETECT CONNECT TIMEOUT, 0 
try { 
final Integer result = request.rest 


AtupRequest .GET, detectPath, Integer.class 

) 
log.debug 

("gdetecting " + atupDevice.getDeviceHost() + " :" + result 
和 

(!result.equals 

(atupDevice.getDeviceStatus () 

) { 


atupDevice.setDeviceStatus 
(result 


) 7 
dao.update 
(atupDevice 


} 
} catch 
(final Exception e 


log.error 
(e 
); 

本 
(!AtupParam.DEVICE ERROR.equals 
(atupDevice. getDevicestatus () 
)) { 

atupDevice.setDeviceStatus 

(AtupParam.DEVICE ERROR 
) 


dao.update 
(atupDevice 


} 
} 
} 
} catch 
(final Exception e 


log.error 
(e 
); 
} 


} 
}, 0, AtupVariable.DETECT INTERVAL, TimeUnit.SECONDS 
Py 


关注 点 4 
: 周期 性 任务 的 间隔 设 定 


在 这 段 代 码 中 ，detectTask 是 ScheduledExecutorService 接 口 的 实现 类 ， 其 方法 schedule WithFixedDelay0 用 于 接受 一 个 周期 执行 的 任务 ， 其 中 定义 了 一 个 执行 线程 ， 见 关注 点 1。 该 线程 用 于 遍历 设 
备 列表 并 探测 其 状态 ， 见 关注 点 2。REST 请 求 连接 超时 设 定 为 AtupVariable.DETECT CONNECT_TIMEOUT， 类 型 为 整 型 ， 见 关注 点 3。 周 期 性 执行 的 线程 设 定 间隔 为 AtupVariable.DETECT_INTERVAL， 
类 型 为 长 整 型 ， 单 位 是 秒 ， 见 关注 点 4。 


可 以 通过 以 下 命令 触发 探测 流程 : 


Curl -X POST http://localhost:8080/atup-device/rest-api/devices/status 


(2) 优先 队列 


在 测试 作业 从 生成 到 下 发 的 过 程 中 ， 测 试 作业 按照 优先 级 顺序 缓存 在 优先 队列 中 。ATUP 定 义 了 3 种 优先 级 ， 分 别 是 最 高 (HIGH=0) 、 普 通 (MEDIUM=1) 和 最 低 (LOW=2) 。 优 先 队列 的 设计 和 实 
现 有 多 种 办 法 ，ATUP 使 用 堆 来 实现 。JDK 提 供 的 java.util.PriorityQueue<E> 内 部 使 用 数组 实现 了 小 根 堆 的 数据 结构 ，ATUP 选 用 PriorityQueue 作 为 优先 队列 的 基础 。 


小 白 讲堂 


堆 是 一 种 经 过 排序 的 完全 二 又 树 ， 其 中 任 一 非 终 端 结 点 的 数据 值 均 不 大 于 (或 不 小 于 ) 其 左 叶 子 和 右 叶 子 结 点 的 值 。 最 大 堆 和 最 小 堆 是 二 又 堆 的 两 种 形式 。 最 大 堆 : 根 结 点 的 键 值 是 所 有 堆 结 点 键 值 中 
最 大 者 。 最 小 堆 : 根 结 点 的 键 值 是 所 有 堆 结 点 键 值 中 最 小 者 。 


有 了 优先 队列 后 ， 要 为 其 提供 比较 方法 。PriorityQueue 内 部 支持 Comparator 接 口 和 Comparable 接 口 两 种 实现 ， 优 先 使 用 Comparator 接 口 的 实现 。Comparator 接 口 是 一 种 策略 模式 的 实现 ， 即 被 比 
较 的 实体 类 本 身 无 须 具备 比较 能 力 ， 该 类 的 比较 类 实现 Comparator 接 口 ， 并 将 其 泛 型 类 型 定义 为 该 实体 类 。Comparable 接 口 要 求 被 比较 的 实体 具备 比较 能 力 。 两 者 各 有 优 缺 点 ， 前 者 简化 了 实体 类 的 设 
计 ， 后 者 简化 了 类 的 设计 。 测 试 作业 类 的 设计 实现 了 Comparable 接 口 ， 示 例 代码 如 下 所 示 。 


Q@XmlRootElement 

Public class AtupTestJobInfo extends AtupInfo implements Comparable<AtupTestJobInfo> { 

private Integer jobId; 

private Integer userId; 

Private String deviceIp; 

Private Integer caseld; 

private Integer priority; 

private Long generatedTime; 

http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
QOverride 
public int compareTo 

(AtupTestJobInfo other 

) { 


int result = this.priority.compareTo 
(other.priority 
和 


和 
(result 一 0 


return this.generatedTime .compareTo 
(other.generatedTime 


} else { 
return result; 


} 


在 这 段 代 码 中 ， 首 先 比较 测试 作业 的 优先 级 ， 按 照 Integer 的 比较 规则 ， 正 ( 负 ) 数 1 为 当前 测试 作业 优先 级 高 ( 低 ) 。 如 果 为 0， 两 者 优先 级 相同 ， 接 下 来 比较 测试 作业 生成 时 的 时 间 ， 取 纳 秒 数 
(nano time) ， 这 是 个 Long 型 数值 ， 相 等 几率 非常 低 。 


有 了 理论 依托 ， 我 们 来 设想 一 个 场景 ， 以 检验 代码 实现 是 否 正确 。 如 图 11-6 所 示 ， 按 照 创建 的 时 间 先 后 列 出 了 5 个 待 下 发 的 作业 J1~J5， 对 应 的 测试 用 例 编号 为 C1~C5， 测 试 服务 器 包括 192.168.1.180 
和 192.168.1.181 两 台 虚 拟 机 ， 以 及 本 地 宿主 机 。 作 业 优先 级 分 别 为 高 (H) 、 中 (M) 、 低 (L) 。 


192.168.1.180 


192.168.1.180 


192.168.1.180 | 


我 们 期 待 的 堆 结构 如 图 


图 11-7 所 示 。 


11-6 所 示 ， 优 先 级 最 高 的 是 J1 和 J4， 而 前 者 先 于 后 者 创建 ， 


图 11-6 “创建 测试 作业 示意 图 


因此 排 在 前 面 ， 随 后 是 J)2 和 J， 最 后 是 J3。 并 且 ， 我 们 期 待 优先 级 最 高 的 两 个 项 出 堆 后 ， 罗 辑 排 列 顺 序 是 J2-J5-J3， 如 


图 11-7 ”测试 作业 小 根 堆 示意 图 
测试 作业 队列 PriorityQueue 实 例 的 业务 类 ， 包 括 增加 和 删除 测试 作业 、 查 看 当前 待 下 发 作业 信息 和 下 发 作业 等 功能 。 其 中 ， 获 取 当 前 队列 
因为 堆 的 内 部 结构 和 算法 非 严格 一 致 ， 即 当前 出 队 的 作业 的 优先 级 取 值 永远 最 小 (代表 优先 级 最 高 ) ， 但 在 
此 ， 查 看 当前 待 下 发 作业 信息 的 实现 要 额外 对 获取 的 数组 进行 一 次 排序 ， 这 样 获取 的 列表 顺序 才 和 优先 


验证 部 分 可 以 参考 JobLaunchService 类 ， 该 类 是 封装 和 调 
的 待 下 发 作业 信息 的 实质 是 对 PriorityQueue 实 例 内 部 数组 的 遍历 ， 但 这 个 说 法 其 实 是 不 正确 的 ， 
其 内 部 数组 中 的 顺序 不 是 照 此 安排 的 。 可 参见 PriorityQueue 类 的 siftUp( 方 法 和 siftDown() 方 法 。 因 
级 逻辑 一 致 。 示 例 代码 如 下 所 示 。 


public AtupTestJobListInfo getJobs() { 
AtupTestJobInfo[] jobs = jobQueue.toArray 

(new AtupTestJobInfo[jobQueue.size()] 

和 


将 
(jobs.length > 0 
主导 


Arrays.sort 

(jobs 
下 

} 

return new ALupTestJobListInfo 
(Arrays.asList 
(jobs 
j) 

} 


(3) 并 发 下 发 


按照 设备 状态 和 优先 队列 的 讲述 ， 我 们 可 以 设想 测试 作业 是 按照 如 图 11-8 所 示 的 顺序 下 发 并 返回 测试 结果 的 。 


的 下 发 方式 ， 即 一 个 接 一 个 地 下 发 。 但 这 在 实际 生产 中 是 不 可 能 的 ， 我 们 需要 谨慎 地 考虑 并 发 问题 。 使 用 PriorityQueue 类 非常 方便 地 实 
量 复 下 发 或 者 同时 向 一 个 设备 下 发 多 个 作业 导致 设备 忙 


但 是 ， 图 11-8 的 这 个 设想 基本 上 是 错误 的 ， 除 非 我 们 使 用 串 行 | 
现 堆 结构 的 时 候 ， 切 不 可 太 过 随意 ， 因 为 这 个 类 不 是 线程 安全 的 ， 并 且 不 建议 在 多 线程 中 使 用 。 一 个 很 典型 的 并 发 问题 是 下 发 操作 会 对 同一 个 作业 刀 
碌 ， 测 试 作业 有 丢失 的 可 能 。 另 外 ， 优 先 队 列 的 插入 操作 和 删除 操作 是 通过 页 面 完 成 的 ， 和 下 发 出 队 操 作 不 在 一 个 线程 中 ， 也 需要 考虑 。 


LocalHost 


TestStation1 (192.168.1.180) 


TestStation2 (192.168.1.181) 


Time 


11-8 测试 作业 下 发 顺序 示意 图 


解决 并 发 问题 的 核心 是 锁 的 使 用 和 锁 粒 度 的 掌握 。 如 果 粒 度 过 大 ， 会 导致 串 行 ， 甚 至 出 现 互 锁 导 致 的 死 锁 。 粒 度 过 小 ， 就 无 法 保证 业务 完整 地 按 顺 序 执行 。 在 下 发 方法 中 ， 应 当 针对 设备 1P 锁 定 ， 保 证 


同一 设备 测试 作业 的 串 行 (测试 设 备 运行 测试 后 状态 为 忙碌 ， 应 当 等 待 其 空 闪 时 再 下 发 新 的 测试 作业 ) 。 代 码 示例 如 下 所 示 。 


synchronized 
(jobQueue 
a 双人 
关注 点 1 
: 锁 jobQueue 
jobInfo = jobQueue.poll (); 
deviceIP = jobInfo.getDeviceIp(); 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
} 
if 
(jobInfo != null 
) 


synchronized 
(lockMap.get 
(deviceIp 
)}) 4 

if 
(deviceIp.matches 
(IP_PATTERN 
) 

11 deviceIP.toUpPerCase () .equals 
("LOCALHOST" 
217 4 

final AtupDevice testDevice = fetchDeviceFromDB 

(deviceIp 


Integer deviceStatus = testDevice.getDeviceStatus (); 


站 

(AtupParam.DEVICE IDLE.equals 
(gevicestatus 
)) 1 

final AtupTestCase testCase = fetchTestCaseFromDB 
(jobInfo.getCaseId() 

launchTest 
(jobInfo.getUserId(), testDevice, testCase 

return true; 


了 


在 这 段 代 码 中 ， 首 先是 控制 锁 力度 ， 见 关注 点 1， 这 里 只 将 与 作业 队列 操作 相关 的 部 分 锁 住 ， 在 没有 涉及 优先 队列 操作 的 地 方 无 须 将 锁 粒 度 定 为 jobQueue。 另 外 ， 如 果 当 前 测试 作业 出 堆 后 ， 没 有 满足 
条 件 或 者 异常 导致 下 发 失败 ， 应 当 将 其 重新 入 堆 ， 确 保 逻 辑 上 事务 的 原子 性 。 详 见 org.feuyeuxjaxrs2.atup.cases.service.JobLaunchSservice 类 。 


(4) 异步 响应 


二 上 


本 部 分 是 对 第 8 章 的 实践 ， 原 理 可 参考 该 章 。 业 务 罗 辑 是 下 发 过 程 中 ，ATUP CASE 服 务 器 无 须 等 待 ATUPTest Station 测 试 服务 器 运行 测试 即 可 返回 下 发 结果 给 客户 端 ， 待 ATUPTest Station 测 试 完 毕 ， 
异步 返回 测试 结果 ，ATUP CASE 服 务 器 将 测试 用 例 的 测试 结果 写 入 数据 库 。 详 见 org.feuyeux.jaxrs2.atup.cases.service.JobLaunchService 类 。 


(5) 作业 监控 


测试 作业 的 监控 对 测试 者 和 作业 管理 员 都 非常 有 价值 ， 其 核心 价值 是 时 效 性 和 准确 性 。 这 部 分 的 实现 是 通过 JavasScript 脚 本 的 轮 询 请 求 资源 列表 的 REST 资 源 地 址 实现 的 ， 代 码 示例 如 下 所 示 。 


function loadDevices() { 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 
setInterval 
(restCall, 10000 


} 
function restCall() { 
restGet 
(HOST + ATUP _ CASE BASE URI + TEST JOB PATH, GET METHOD, renderGetAll 


} 


7 持续 发 布 


持续 发 布 的 两 个 关键 参数 是 服务 器 地 址 和 发 布 环境 的 配置 。 前 者 是 对 Nginx 和 Tomcat 服 务 器 的 定位 ， 后 者 是 对 前 述 3 套 环境 中 相关 参数 的 赋值 。 现 在 的 持续 发 布 形式 是 一 键 式 的 ， 即 动态 设置 参数 以 匹 
配 响应 的 部 署 环境 ， 因 此 我 们 需要 定位 一 个 环节 来 动态 地 为 上 述 两 组 参数 赋值 。 构 建 工具 和 集成 测试 平台 都 可 以 做 这 件 事 情 。ATUP 选 用 的 是 构建 工具 Maven。 本 节 将 列举 几 个 关键 点 ， 来 演示 如 何 实现 动 
态 配 置 。 


(1) 服务 器 地 址 


服务 器 是 指 ATUP 各 个 模块 部 署 的 机 器 。 在 不 同 的 环境 中 ， 机 器 的 地 址 是 不 同 的 。 例 如 ， 在 开发 环境 中 ， 各 模块 都 部 署 在 本 地 ， 因 此 服务 器 地 址 就 是 localhost， 端 口 (通常 情况 下 ) 就 是 8080。 集 成 测 
试 环境 中 ， 采 用 了 动静 分 离 ; 生产 环境 中 ， 各 个 模块 单独 部 署 。 因 此 ， 服 务 器 的 地 址 不 能 硬 编码 ， 也 不 能 由 某 个 配置 文件 实现 。 


ATUP 采 用 的 解决 方案 是 为 每 一 种 环境 提供 独立 的 配置 ， 比 如 集成 测试 环境 的 配置 文件 为 atupCommon_stagingjs， 在 Maven 构 建 过 程 中 ， 如 果 目 标 部 署 环境 是 CI 的 ， 就 将 其 蔡 换 为 
atupCommon.js。 这 样 运行 期 就 是 用 这 套 环境 的 服务 器 地 址 。 这 里 要 用 到 的 Maven 插 件 是 maven-antrun-plugin， 相 关 配 置 在 jax-rs2-atup\atup-page\pom.xml 中 ， 参 考 代 码 如 下 所 示 。 


<plugin> 
<groupId>org.apache.maven.plugins</groupId> 
<artifactId>maven-antrun-plugin</artifactId> 
<version>1.7</version> 
<executions> 
<execution> 
<phase>initialize</phase> 
<configuration> 
<target> 
<copy file="src/main/webapp/js/atupCommon staging.js" 
tofile="${project.build.directory}/${project .artifactId}- 
${project .version}/js/atupCommon.js" overwrite="true" /> 
</target> 
</configuration> 
<goals> 
<goal>run</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 


jax-rs2-atup\atup-page\src\main\webapp\js\atupCommon_staging.js 的 内 容 参 考 如 下 代码 。 


Var ATUP CASE HOST = "http://10.11.72.57:8080/"; 
Var ATUP DFEVICE HOST = "http://10.11.72.57:8080/"; 
Var ATUP USER HOST = "http://10.11.72.57:8080/"; 


var ATUP PAGE HOST = "http://10.11.72.57/"; 

var ATUP CASE BASE URI = 'atup-case/rest-api'; 

var ATUP DEVICE BASE URI = 'atup-device/rest-api'; 

Var ATUP USER BASE URI = 'atup-user/rest-api'; 

Var ATUP_ PAGE BASE URI = 'atup-page/'; 

var ATUP CASE URI = ATUP CASE HOST+ATUP CASE BASE URI; 

var ATUP DEVICE URI = ATUP DEVICE HOST+ATUP DEVICE BASE URI; 
var ATUP USER URI = ATUP USER HOST+ATUP USER BASE URI; 

var ATUP PAGE URI =ATUP PAGE HOST +ATUP PAGE BASE URI; 


本 例 是 比较 简单 的 多 个 模块 部 署 在 同一 台 主机 上 的 情况 ， 分 模块 (独立 ) 部 署 见 11.3.4 节 。 


(2) 动态 模块 热 部 署 


Maven 播 件 omcat7-maven-plugin 支 持 Tomcat 的 热 部 署 ， 在 构建 成 功 后 执行 ， 实 现 远程 复制 war 包 并 热 部 署 该 应 用 。 示 例 参考 如 下 ， 在 jax-rs2-atup\pom.xml 中 ， 定 义 Tomcat 服 务 器 地 址 和 端口 。 


<properties> 
<tomcat . server.ip>192.168.1.180</tomcat.server.ip> 
<tomcat .1ocal.Port>8080</tomcat .1ocal.Port> 
</properties> 


在 插件 使 用 的 配置 中 ， 提 供 上 述 参数 ， 以 实现 对 远程 服务 器 的 访问 ,示例 代码 如 下 所 示 。 


<plugin> 
<groupId>org.apache.tomcat .maven</groupId> 
<artifactId>tomcat7-maven-plugin</artifactId> 
<version>$ {tomcat7-maven-plugin.version}</version> 
<configuration> 
<url>http://${tomcat.server.ip}:${tomcat.1local .port}/manager/text</url> 
<server>Atup Tomcat Staging</server> 
</configuration> x 
</plugin> 


在 子 模块 的 配置 中 ， 比 如 jax-rs2-atupNatup-device\pom.xml， 具 体 定 义 触 发 该 插件 执行 的 阶段 (pre-integration-test) 和 复制 war 的 名 称 和 路 径 ， 上 默认 为 target/${project.build.finalName}.war 
和 /$fproject.build.finalName}。 示 例 代码 如 下 所 示 。 


<profile> 
<id>CI</id> 
<build> 
<plugins> 
<plugin> 
<groupId>org.apache.tomcat .maven</groupId> 
<artifactId>tomcat7-maven-plugin</artifactId> 
<executions> 
<execution> 
<phase>pre-integration-test</phase> 
<configuration> 
<warFile>target/$ {project .build.finalName} .war</warFile> 
<path>/$ {project .build.finalName}</path> 
</configuration> 
<goals> 
<goal>redeploy</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 
</plugins> 
</build> 
</profile> 


构建 ATUP 的 主机 需要 添加 Maven 配 置 中 的 服务 器 的 用 户 信息 。.m2/settings.xml 文 件 中 的 参考 配置 如 下 所 示 。 


<servers> 
<server> 
<id>Atup _ Tomcat Staging</id> 
<username>admin</username> 
<password>admin</password> 
</server> 
</servers> 


同时 ， 在 Tomcat 中 需要 建立 该 用 户 信息 。TOMCAT_HOME/conf/tomcat-users.xml 文 件 中 的 参考 配置 如 下 所 示 。 


<?xml version= 
“1.0 
”encoding= 


<tomcat-users> 
<role rolename: 
<role rolename: 
<user username: 
</tomcat-users> 


manager-gui"/> 
manager-script"/> 
admin" password="admin" roles="manager-script,manager-gui"/> 


执行 动态 模块 的 部 署 ， 可 以 使 用 Maven 的 构建 命令 ， 示 例如 下 所 示 。 


mvn clean install -DskipTests -Dtomcat.server.ip=192.168.1.181 -PCI 


其 中 ，-D 后 跟随 构建 中 用 到 的 变量 键 值 对 ，-P 后 跟随 Maven 配 置 中 profile 名 称 。 


(3) 静态 模块 热 部 署 


因为 在 静态 服务 器 中 没有 虚拟 机 的 概念 ， 所 以 静态 模块 部 署 的 实质 是 文件 复制 。 基 本 思路 是 使 用 Maven 的 Ant 插 件 调用 远程 复制 命令 scp， 示 例 代码 如 下 所 示 。 


<profile> 
<id>CI</id> 
<build> 
<plugins> 
<plugin> 
<groupId>org.apache.maven.plugins</groupId> 
<artifactId>maven-antrun-plugin</artifactId> 
<version>1.7</version> 
<executions> 
<execution> 
<id>deploy package</id> 
<phase>package</phase> 
<configuration> 
<target> 
<scp todir="${u}:${p}@${h}:/${d}" 
trust="true" failonerror="true"> 


<fileset 
dir="${project.build.directory}/ 
${project.artifactId}-${project.version}" /> 
</scp> 
</target> 
</configuration> 
<goals> 
<goal>run</goal> 
</goals> 
</execution> 
</executions> 
<dependencies> 
<dependency> 
<groupId>org.apache.ant</groupId> 
<artifactId>ant-jsch</artifactId> 
<version>1.9.2</version> 
</dependency> 
<dependency> 
<groupId>com.jcraft</groupId> 
<artifactId>jsch</artifactId> 
<version>0.1.50</version> 
</dependency> 
</dependencies> 
</plugin> 
</plugins> 
</build> 
<properties> 
<h>$ {nginx.server.ip}</h> 
<u>erichan</u> 
<p>han</p> 
<d>/usr/share/nginx/html/atup-page</d> 
</properties> 
</profile> 


执行 静态 部 署 的 基本 命令 如 下 。 


mvn clean install -DskipTests -PCI 


基本 命令 很 难 满足 多 样 的 部 署 环境 ， 因 此 ， 执 行 命令 中 为 参数 赋值 是 更 可 取 的 办 法 ， 这 样 做 的 好 处 是 ， 避 免 每 次 切换 部 署 环境 时 ， 修 改 Maven 配 置 文件 。 命 令 参考 示例 如 下 所 示 。 


mvn clean install -DskipTests -Du=eric -Dp=han -Dd=/home/eric/nginx/atup-page/ -PCI 


(4) 数据 库 部 署 


Maven 揪 件 sql-maven-plugin 为 构建 期 间 操作 远程 数据 库 提供 了 可 能 。 在 ATUP 到 根 配置 文件 jax-rs2-atup\pom.xml 中 定义 MySQL 服 务 器 的 访问 信息 ， 参 考 代 码 如 下 。 


<plugin> 
<groupId>org.codehaus .mojo</groupId> 
<artifactId>sql-maven-plugin</artifactId> 
<version>${sql-maven-plugin.version}</version> 
<dependencies> 
<dependency> 
<groupId>mysql</groupId> 
<artifactId>mysql-connector-java</artifactId> 
<version>$ {mysql-connector.version}</version> 
</dependency> 
</dependencies> 
<configuration> 
<driver>com.mysql.jdbc.Driver</driver> 
<url>jdbc:mysql://${mysql.server.ip}:3306</url> 
<username>root</username> 
<password>root</password> 
</configuration> 
</plugin> 


子 模块 的 配置 文件 modules/pom.xml 中 定义 了 触发 插件 执行 的 阶段 (pre-integration-test) 和 触发 操作 (执行 见 表 脚 本 atup-user.sql) 。 


<plugin> 
<groupId>org.codehaus .mojo</groupId> 
<artifactId>sql-maven-plugin</artifactId> 
<executions> 
<execution> 
<id>create-db</id> 
<phase>pre-integration-test</phase> 
<goals> 
<goal>execute</goal> 
</goals> 
<configuration> 
<srcFiles> 
<srcFile>http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/O0EBPS/Text/../document/atup-ddl/atup-user.sql</srcFi 
</srcFiles> - 
</configuration> 
</execution> 
</executions> 
</plugin> 


数据 库 的 部 署 命令 参考 如 下 。 


mvn clean install -DskipTests -Dmysql.server.ip=10.11.72.57 
ST 


数据 库 的 部 署 通 常 是 在 Cl 环 境 中 使 用 ， 因 为 开发 环境 使 用 本 地 数据 库 ， 其 测试 数据 不 宜 每 次 都 删除 。 单 元 测试 通常 使 用 内 存 数 据 库 ， 无 须 MySQL。 生 产 环境 中 ， 部 署 环节 通常 不 应 该 对 数据 库 进行 减法 
操作 ， 加 法 操作 也 相对 谨慎 。 


(5) 发 布 版 本 号 


发 布 版 本 号 是 每 次 构建 和 部 署 的 唯一 标识 ， 在 CI 测试 阶段 可 以 有 效 落实 缺陷 所 处 的 版 本 ， 对 于 UI 测试 尤为 
建 时 间 赋 值 给 指定 的 token。 根 配置 jax-rs2-atup\pom.xml 参 考 如 下 ， 这 里 定义 了 根 目录 路 径 。 


和 要。 如何 为 每 次 构建 和 部 署 生成 唯一 标识 呢 ? 这 里 使 用 了 Maven 的 replacer 揪 件 ， 动 态 将 构 


<properties> 
<main.basedir>$ {project .basedir}</main.basedir> 
</properties> 


子 模块 配置 jax-rs2-atupNatup-page\pom.xml 参 考 如 下 ， 定 义 了 根 目录 路 径 和 覆盖 token 的 实现 。 


<properties> 
<main.basedir>$ {project .parent .basedir}</main.basedir> 
</properties> 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


<profile> 
<id>CI</id> 
<build> 
<plugins> 
<plugin> 
<groupId>com.google.code.maven-replacer-plugin</groupId> 
<artifactId>replacer</artifactId> 
<version>1.5.2</version> 
<executions> 
<execution> 
<phase>valigdate</phase> 
<goals> 
<goal>replace</goal> 
</goals> 
</execution> 
</executions> 
<configuration> 
<file> 
$ {main.basedir}/atup-page/src/main/ 
webapp/js/index buildtime.js 
</file> 
<outputFile> 
$ {main.basedir}/atup-page/src/main/webapp/js/index.js 
</outputFile> 
<replacements> 
<replacement> 
<token>Q@buildtime@</token> 
<value>$ {maven.build.timestamp}</value> 
</replacement> 
</replacements> 
</configuration> 
</plugin> 
</plugins> 
</build> 
</profile> 


jax-rs2-atup\atup-page\src\main\webapp\js\index_buildtime.js 中 定义 了 名 为 buildtime 的 token， 在 执行 期 替换 为 构建 时 间 $fmaven.build.timestamp} 变 量 ， 然 后 将 该 文件 内 容 覆 盖 ， 输 出 到 


${main.basediryatup-page/src/main/webapp/js/indexjs 文 件 ， 这 个 文件 是 最 终 运 行 期 使 用 的 脚本 文件 。 


function markVersion() { 
jQuery 

('#buildDiv' 

) .html 

("Build Time: @buildtime@" 

i 

} 


(6) 数据 库 连 接 


如 果 不 使 用 JNDI 配 置 ， 那 么 数据 库 的 配置 信息 就 会 公布 在 程序 中 ， 这 样 一 方 | 
件 中 的 变量 动态 赋值 。 


不 符合 安全 的 要 求 ， 另 一 方面 很 难 支 持 多 种 环境 的 部 署 。 这 里 使 


回 


在 JPA 的 配置 文件 ax-rs2-atupNatup-usemsrc\mainNresources\META-INF\persistence.xml 的 JDBC 配 置 中 启用 参数 。 


Maven 的 properties-maven-plugin 揪 件 实现 为 配置 文 


<!-- Connection JDBC --> 
<properties> 
<property nam 


avax.persistence.jdbc.driver" value="${db.driver}"/> 
<property nam avax.persistence.jdbc.url" value="${db.url}"/> 
<property name="javax.persistence.jdbc.user" value="${db.username}"/> 
<property name="javax.persistence.jdbc.password" value="${db.password}"/> 
</properties> 


创建 参数 键 值 对 配置 文件 jax-rs2-atup\atup-user\src\main\resources\section\staging.properties。 


.Server.address=10.11.72.54 

.driver=com.mysql .jdbc.Driver 
.url=jdbc:mysql://${db.server.address}:3306/jaxrs2 atup 
.username=root i 
.Password=root 


88888 


编辑 Mavne 配 置 文件 jax-rs2-atup\atup-user\pom.xml， 执 行 插件 的 read-project-properties， 将 其 目标 定义 为 上 述 的 键 值 对 文件 ， 这 样 构建 后 的 JPA 配 置 中 就 会 将 参数 键 蔡 换 成 参数 值 。 


<profile> 
<id>CI</id> 
<build> 
<plugins> 
<plugin> 
<groupId>org.codehaus .mojo</groupId> 
<artifactId>properties-maven-plugin</artifactId> 
<version>1.0-alpha-2</version> 
<executions> 
<execution> 
<phase>initialize</phase> 
<goals> 
<goal>read-project-properties</goal> 
</goals> 
<configuration> 
<files> 
<file> 
src/main/resources/section/staging.properties 
</file> 
</files> 
</configuration> 
</execution> 
</executions> 
</plugin> 
</plugins> 
</build> 
</profile> 


(7) 单元 测试 和 集成 测试 


元 测试 代码 使 用 TU 前 级 ， 对 方法 功能 进行 测试 。 集 成 测试 前 缀 是 TI。 示 例如 下 所 示 。 


@ContextConfiguration 

(locations = {"classpath:applicationContext2.xml"} 
) 

@RunWith 

(SpringJUnit4ClassRunner.class 


public class TUAtupUserDao { 
private final Logger 10g = LogManager.getLogger 
(TUAtupUserDao.class.getName ( 
7 
@Autowired 
private AtupUserDao dao; 


QTest 

public void testCreateUser () { 
final AtupUser user = CreateUser.buildUser () 
final AtupUser newUser = dao.save 


(user 
); 
1og.info 
(newUser 
yo 
Assert .assertEquals 
(user.getUserName (), newUser.getUserName() 
由 
这 段 代码 使 用 了 applicationContext2.xml 文 件 作为 Spring 的 环境 配置 ， 和 运行 环境 的 主要 区 别 是 没有 使 用 容器 配置 的 JNDI 作 为 JPA 的 数据 集 ， 而 是 采用 本 地 配置 jpaMysql2。 
在 Maven 的 配置 中 ， 为 测试 建立 名 为 TI 的 profile， 参 考 代码 如 下 。 
<profile> 
<id>TI</id> 
<build> 
<plugins> 
<plugin> 
<groupId>org.apache.maven.plugins</groupId> 
<artifactId>maven-failsafe-plugin</artifactId> 
<version>$ {maven-failsafe-plugin.version}</version> 
<configuration> 
<includes> 
<include>**/**/**/**/**/TU**.java</include> 
<ineludes /re /rt /TI , Tavax/inclade> 
</includes> 
</configuration> 
<executions> 
<execution> 
<goals> 
<goal>integration-test</goal> 
<goal>verify</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 
</plugins> 
</build> 
</profile> 
11.3.2 ”Sprint2 模 块 功能 
在 完成 基础 功能 后 ， 我 们 进入 下 一 个 Sprint 来 实现 各 个 模块 的 功能 。 下 面 逐 一 讲述 实现 用 户 模块 、 设 备 模块 和 用 例 模块 过 程 中 的 要 点 。 
1. 用 户 模块 
ATUP 采 用 动静 分 离 的 多 模块 单机 部 署 拓 扑 ， 默 认 情况 下 多 模块 之 间 的 会 话 信息 无 法 共享 。 因 此 ， 本 示例 采用 的 策略 是 在 用 户 登 录 后 ， 静 态 服务 器 上 的 脚本 将 用 户 的 角色 信息 保存 在 浏览 器 端 ， 使 用 的 是 


HTML5 的 Web Storage 技 术 。 


小 白 讲堂 


HTML5 Web Storage 相 比 Cookie 更 安全 和 快速 。 数 据 以 键 值 对 形式 存储 ， 支 持 存储 较 大 的 数据 ， 而 不 影响 性 能 。 这 上 比 Cookie 只 有 4kB 容 量 的 限制 要 强大 许多 。Web Storage 包 括 两 种 类 型 ， 其 中 localStorage 用 
于 存储 不 过 期 的 数据 ， 在 浏览 器 关闭 后 ， 数 据 依 然 有 效 ; sessionStorage 用 于 存储 会 话 生命 周期 的 数据 。Firefox、Chrome、Internet Explorer 8+、Safari 和 Opera 浏 览 器 都 支持 Web Storage。 


(1) 注册 和 登录 


ATUP 的 注册 页 面 是 atup-page/src/main/webapp/signUp.html， 对 应 的 脚本 文件 是 atup-page/src/main/webapp/js/users/user.js, 


式 遵循 上 文 讲述 的 REST 请 求 。 


<input id="createButton" type="button" value="Create" onclick="createUser();"/> 
function createUser() { 
Var userName = jQuery.trim 
(jQuery 
("#userNameO" 
) .val() 
); 
Var password = jQuery 
("#passwordO" 
) .val(); 
Var hashPassword = md5 
(password 
); 
Var PostData = JSON.stringify 
( 
{userName: userName, passWord: hashPassword, userRole: 4, status: 0} 
yy 
restSet 
(HOST + ATUP USER BASE URI + USER PATH, POST METHOD, postData, renderCreate 
| 
} 


ATUP 注 册 上 
的 脚本 文件 是 atup-page/src/main/webapp/js/index_buildtime.js。 登 录 页 
例 代 码 片段 如 下 所 示 。 


于 请 求 服务 器 验证 


对 


当前 


户 信息 ， 


并 保存 


于 管理 员 创建 普通 


户 。 代 码 片段 如 下 ， 页 面部 分 的 处 理 方 


户 登录 页 面 是 atup-page/src/main/webapp/signin.html， 对 应 的 脚本 文件 是 atup-page/src/main/webapp/js/users/user.js; 首页 是 atup-page/src/main/webapp/index.html， 对 应 


户 ID 到 HTML5 的 sessionStorage 中 ， 然 后 根 


居 用 户 权 限 动态 生成 首页 信息 。 示 


[ae 
关注 点 1 
: 登录 按钮 


<input id="signInButton" type="button" value="Sign In" onclick="signIn();"/> 


function signIn() { 

Var userName = jQuery 
("#userName" 
) .val(); 

Var password = jQuery.trim 
(jQuery 
("#password" 
) .val() 
内 这 

Var hashPassword = md5 
(password 
); 

Var url = HOST + ATUP USER BASE URI + SIGNIN _ PATH 


+ "?user=" + userName + "&password=" + hashPassword; 
restGet 
(url, GET METHOD, renderSignIin 


2 
} 
// 


关注 点 3 
: 登录 回调 方法 
function renqerSignIn 
(data 
Fr 
if 
(data.userId != null && data.userName != null && data.userRole != null 


St 


storage.setItem 


("userId", 


data.userId 


storage.setItem 


); 


storage.setItem 


Li 


("userName", data.userName 


"userRole", data.userRole 


window.location.href = "index.html"; 


} 
// 
关注 点 4 
: 按 角 色 泻 染 


页 面 方法 


function loadLinkByRole() { 
Var userRole = storage.getItem 


); 
en 
(userRole 


) { 


"userRole" 


一 ROLE ADMIN 


jQuery 
('#userDiv' 


) .html 
( 


} else 
(userRole 


{ 


http: //www. 


} else 
(userRole 


) { 


http: //www. 


} else 
(userRole 


Ss 


http: //www. 


} 


"<div><h5>Users</h5></div>" + 
"<a href='users/users.html'>User List</a><br/>" + 
"<a href='users/user.html'>Manage User</a><br/>" 


if 


一 ROLE JOB KILLER 


if 


一 ROLE DEVICE MANAGER 


1 
一 ROLE USER 


hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/0EBPS/Text/... 


hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


在 这 段 代 码 中 ， 分 别 定义 了 登录 按钮 、 登 录 方 法 、 登 录 回 调 方法 和 按 角色 演 染 页 面 方法 ， 分 别 见 关注 点 1~ 关 注 点 4。 这 号 


在 


登录 成 功 


(2) 认证 和 


静态 页 面 对 


权 


党 


function checkSignIn() { 
Var storageUserId = Storage.getItem 


("userId" 
bb 


(storageUserId == null 
) 


{ 


的 回调 函数 rendersignln0 中 保存 的 。 另 外 ， 用 户 名 称 用 于 页 面 显 示 。 


window.location.href = HOST + ATUP PAGE BASE URI + "signIn.html"; 


} else 


{ 


Var user = storage.getItem 


2 


("userName" 


授权 是 通过 动态 生成 符合 当前 角色 的 HTML 内 容 实 现 的， 而 认证 是 通过 页 面 加 载 时 调用 脚本 函数 完成 的 ， 示 例 代码 如 下 所 示 。 


要 说 明 的 是 ，REST 请 求 最 终 进 入 rest0 方 法 后 所 用 到 的 用 户 ID 和 用 户 角 色 信 息 是 


Var welcomeDiv = jQuery 

('#topDiv' 

) .html 

("Welcome " + user 

a 

1 } 

在 第 3 章 中 ， 我 们 讲述 过 使 用 @Context 注 解 获取 请 求 头 信息 ，createUser() 方 法 中 可 以 得 到 脚本 函数 rest0 提 供 的 用 户 ID 和 用 户 角色 信息 。 由 头 信息 得 到 当前 用 户 的 角色 ， 然 后 根据 角色 决定 当前 资源 是 
否 可 以 被 其 使 用 。 如 果 没有 用 户 角 色 信息 或 者 用 户 角色 不 符合 要 求 ， 那 么 将 遵循 第 3 章 所 述 的 处 理 响 应 的 要 求 ， 直 接 返 回 错误 信息 。 

服务 器 端的 认证 是 通过 对 请 求 头 信息 处 理 来 实现 的 ， 授 权 是 通过 编码 完成 的 ， 示 例 代 码 如 下 所 示 。 

@POST 

Q@Produces 


(MediaType .APPLICATION JSON 
) eo 


@Consumes 


(MediaType .APPLICATION JSON 
) 2 


public javax.ws.rs.core.Response createUser 


Q@Context final HttpHeaders headers, final AtupUserInfo userInfo 


于 过 


Response 


) 7 
入 下 
(response 


3 所 


response = checkRole 


= null 


(headers, AtupParam.USER ADMIN 


return createUser 


(userInfo 
到 


9 else { 


return response; 


有 


} 
public Response checkRole 
(HttpHeaders headers, Integer role 


关于 


Integer UserId = Integer.valueOf 


headers .getRequestHeader 
(AtupApi .ATUP_USER HEAD 


) .get 
(0 
由 二 这 


Integer userRole = Integer.valueOf 


headers .getRequestHeader 
(AtupApi .ATUP USER ROLE HEAD 
) .get 
(0 

7 


应 
(userId == null 


final AtupUserInfo result = 
new AtupUserInfo 
("No user info found.", AtupErrorCode.UNAUTHORIZED ERROR 
小 水 加 


return Response.status 

并 
Response.Status .INTERNATL SERVER ERROR 
) .entity 
(result 
} buildt)y 
} else { 

final AtupUser user = service.getUser 

(userId 


还 
(!user.getUserRole () .equals 
(role 
) || !userRole.equals 
(role 
bP 
final AtupUserInfo result = 
new AtupUserInfo 
("No permission for this request.", 
AtupErrorCode .FORBIDDEN ERROR 


); 
C 


return Response.status 


Response.Status.INTERNAL SERVER ERROR 
) .entity 
(result 
) .build()， 
} else { 
return null; 
} 


(3) Web Storage 与 多 Tab 


通常 ， 浏 览 器 端 存 储 让 开发 者 忌 刁 的 是 多 Tab 对 会 话 的 影响 ， 这 里 要 明确 的 是 ，sessionStorage 的 作用 域 是 当前 Tab。 如 果 新 打开 一 个 Tab 并 复制 前 一 个 Tab 登 录 后 访问 的 地 址 ， 新 Tab 页 面 会 跳 转 到 登 
录 页 面 ， 这 正 是 我 们 期 待 的。 使 用 Chrome 浏 览 器 试验 如 下 。 


在 第 一 个 Tab 中 ， 启 用 开发 者 工具 (快捷 键 是 <F12> ) 查看 sessionStorage， 因 为 该 页 面 已 经 登录 ， 所 以 会 有 当前 会 话 的 用 户 信息 ， 如 图 11-9 所 示 。 


打开 第 二 个 Tab， 输 入 http://localhost:8080/atup-page， 页 面 自动 跳 转 到 登录 页 面 ， 查 看 该 Tab 页 面 的 sessionStorage， 发 现 内 容 为 空 ， 如 图 11-10 所 示 。 


i Atup Index 


Welcome a 


Elements | Resources | Network Sources Timeline Profiles Audits Console 


pO Frames 
自 web SQL 
上 IndexedDB 
kb Local Storage 
" 转 Session Storage 
=3 http://localhost8080 
医 Ee Cookies 
三 Application Cache 


Userharme 


图 11-9 ” Chrome 开发 者 工具 中 的 Session Storage 示 意图 1 


EE Sign In 


User Name: 


Password: 


Elements | Resources | Netywork Sources Timeline Profiles Audits 四 


kb Frames 
由 Web SQL 
FiIndexedDB 
be 国 Local Storage 
了 转 Session Storage 
33 http://localhost:8080 
= BS Cookies 
国 Application Cache 


图 11-10 ” Chrome 开发 者 工具 中 的 Session Storage 示 意图 2 


(4) 跨 域 访问 


ContainerResponseFilter 接 口 ， 而 且 在 filter() 方 法 的 实现 中 ， 对 响应 头 进行 跨 域 相 关 的 头 字段 进行 填充 。 示 例 代码 如 下 所 示 。 


| Value 


因为 ATUP 是 动静 分 离 ， 但 模块 分 别 部 署 ， 所 以 另 一 个 要 考虑 的 问题 是 跨 域 访 问 。 因 此 ， 需 要 在 ATUP 的 核心 模块 中 实现 跨 域 设置 。AtupCrossDomainFilter 类 分 别 实现 了 ContainerRequestFilter 和 


QOverride 
public void filter 
(final ContainerRequestContext requestContext, 
final ContainerResponseContext responseContext 
) throws IOException { 
responseContext .getHeaders () .add 
("Access-Control-Allow-Origin™, "xm 
) 3; 
responseContext .getHeaders () .add 
("Access-Control-Allow-Headers", 
"origin, content-type, accept, authorization, Atup-User, Atup-UserRole" 
) 3; 
responseContext .getHeaders () .add 
("Access-Control-Allow-Credentials", "true" 


responseContext .getHeaders () .add 
("Access-Control-Allow-Methods", 

"GET, POST, PUT, DELETE, OPTIONS, HEAD" 
于 
responseContext .getHeaders () .add 
("Access-Control-Max-Age", "1209600" 


i 


模块 的 *Application 中 需要 注册 该 类 ， 示 例 代码 如 下 所 示 。 


register 
(org. feuyeux.jaxrs2.atup.core.util.AtupCrossDomainFilter.class 


同时 ，Nginx 的 配置 也 要 考虑 跨 域 访问 。 


add header 'Access-Control-Allow-Origin' '*'; 

add header 'Access-Control-Allow-Credentials' 'true'; 

add header 'Access-Control-Allow-Headers' 

"origin, Content-Type, Accept, Atup-User, Atup-UserRole'; 

add header 'Access-Control-Allow-Methods' "GET， POST, PUT, DELETE, OPTIONS, HEAD'; 
add header 

‘Access-Control-Max-Age 

’ 


‘1209600 
让 


了 


2. 设 备 模块 


设备 模块 的 实现 需要 考虑 两 个 细节 ， 即 纯 HTML 页 面 间 参 数 的 传递 和 页 面 定时 刷新 设备 状态 。 


(1) 设备 管理 页 面 传 参 


在 设备 管理 脚本 jax-rs2-atup\atup-page\src\main\webapp\js\devices\device.js 中 ， 首 先 会 处 理 待 管理 设备 的 传 入 参数 ， 示 例 代码 如 下 所 示 。 


if 


(query 
下 


jQuery 


("#deviceIp" 


) .val 


(getValue 
(query, "deviceIp" 


jQuery 


("#deviceName" 


) .val 


(getValue 


(query, "deviceName 


jQuery 


("#deviceType" 


) .val 


(getValue 


(query, "deviceType 


jQuery 


("#devicestatus" 


) .val 


(getValue 
(query, "devicestatus" 


} 


这 样 做 的 好 处 是 ,方便 更 新 设备 的 所 有 者 。 


(2) 设备 列表 页 面 轮 询 


创建 设备 时 ， 有 一 个 小 的 技巧 就 是 将 设备 状态 设 为 ERROR， 这 样 做 的 目的 在 于 让 后 台 探 测 线程 去 决定 一 个 设备 的 正确 状态 。11.3.1 节 的 测试 作业 分 派 中 讲述 了 探测 的 实现 。 


设备 列表 页 面 定时 对 列 出 的 所 有 者 拥有 的 设备 进行 状态 的 探测 ， 设 备 管理 员 角色 可 以 查看 全 部 设备 的 状态 等 信息 。 


例 模块 


例 模 块 的 


(1) 测试 用 例 页 面 的 测试 集 列表 


点 是 将 静态 的 测试 


测试 


例 必 须 


属于 某 个 测试 集 ， 


例 和 与 之 相关 的 运行 期 测试 作业 之 间 有 机 地 结合 ， 并 在 测试 设备 上 完成 对 测试 用 例 的 测试 。 


此 其 管理 


面 在 加 载 时 会 将 已 有 测试 集 以 select 列 表 标 签 组 织 ， 示 例 代 码 如 下 所 示 。 


function initial() { 


re: 


stGet 


(ATUP CASE URI + TEST SUITE PATH 
+ "/suites?start=0&size=100", GET METHOD, renderSuiteList0 


); 
} 


function renderSuiteList0 


(gata 
) 


Var html = renderSuites 


(gata 
); 
jQ 


uery 


("#suiteListO" 


E 
); 
} 
functi 

(gata 
) { 
Var 1i 
Var ht 


(list 


) .empty () .append 
html 


on renderSuites 


st = data.suiteList; 


ml = 


1 


(i, suite 


2 本 


jQuery.each 
function 


html += "<option value=\""; 


html += suite.suiteId + "\">"; 


html += suite.suiteName + "</option>"; 


} 
) 


return html7 


(2) 测试 作业 页 面 的 设备 列表 


测试 作业 的 创建 依赖 于 测试 设备 ， 原 理 同 上 面 的 测试 集 列表 ， 示 例 代码 如 下 所 示 。 


function initial() { 


re: 


stGet 


(ATUP DEVICE URI + DEVICE PATH, GET METHOD, renderDeviceList 


); 

i 

functi 
(data 

) { 

Var 1i 

Var ht 


(list 


on renderDeviceList 


st = data.deviceList; 


ml = "ny; 
jQuery.each 
function 


1 


(i, device 
{ 


html += "<option value=\""; 
html += device.deviceHost + "\">"; 
html += device.deviceName + "</option>"; 


} 
) 7 


jQuery 
("#deviceList" 
) .empty () .append 


(html 


} 


(3) 测试 作业 列表 页 面 轮 询 


测试 作业 列表 页 面 定 时 从 作业 队列 中 查询 待 处 理 作业 情况 ， 以 便 监控 作业 下 发 线程 的 工作 状态 ， 示 例 代 码 如 下 所 示 。 


function loadJobs() { 


http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/... 


setInterval 
(restCall, 10000 
); 
} 
function renderGetAll 
(data 
x 
var list = data.jobs; 

if 
(list =—= null || list.length =— 0 
| 

jQuery 

("#jobsDiv" 
) .html 
"No job is arranging." 
本 党 


se 
Var userRole = storage.getItem 
("userRole" 
EF 


if 
(ROLE_JOB KILLER == userRole 
二 本 
jQuery 
("#jobsDiv" 
) .html 


( 

"<div align='left'>" + SPAN BEGIN 
"Job Id</span>" + SPAN BEGIN 
"Case Id</span>" + SPAN BEGIN2 
"Device Ip</span>" + SPAN BEGIN 
"User Id</span>" + SPAN BEGIN2 
"Job Priority</span>" + SPAN BEGIN 
"Create Time</span>" + SPAN BEGIN 
"Manage</span></div>" 


十 十 十 十 十 十 十 


); 

jQuery.each 
(list, function 
(i, jobInfo 
) { 

var line = "<div align='left'>" + SPAN BEGIN 
jobInfo.jobId + "</span>" + SPAN BEGIN 
jobInfo.caseId + "</span>" + SPAN BEGIN2 
jobInfo.deviceIp + "</span>" + SPAN BEGIN 
jobInfo.userId + "</span>" + SPAN BEGIN2 
jobInfo.priority + "</span>" + SPAN BEGIN 


十 十 十 十 十 十 十 


"<input type='button' value="'REMOVE" 
onclick="'removeJob 

" + jobInfo.jobId + " 

) ;'/></span></div>"; 

jQuery 

"#jobsDiv" 

) .append 

(line 

) 3; 


} 

); 
} else { 

jQuery 
("#jobsDiv" 
) .html 
( 

"<div align='left'>" + SPAN BEGIN 

"Job Id</span>" + SPAN BEGIN 
"Case Id</span>" + SPAN BEGIN 
"Device Ip</span>" + SPAN BEGIN 
"User Id</span>" + SPAN BEGIN2 
"Job Priority</span>" + SPAN BEGIN 
"Create Time</span></div>" 


十 十 十 十 十 十 


人 
jQuery.each 
(list, function 
(i, jobInfo 
bP 
var line = "<div align='left'>" + SPAN BEGIN 
+ jobInfo.jobId + ™</span>" + SPAN BEGIN 


+ JobInfo.caseId + "</span>" + SPAN BEGIN 
+ jobInfo.deviceIp + "</span>" + SPAN BEGIN 
+ jobInfo.userId + "</span>" + SPAN BEGIN2 
+ jobInfo.priority + "</span>" + SPAN BEGIN 
+ jobInfo.generatedTime + "</span></div>"; 
jQuery 
("#jobsDiv" 
) .append 


(line 
); 


); 


jobInfo.generatedTime + "</span>" + SPAN BEGIN 


11.3.3 lteration1 的 演示 和 回顾 


在 关注 如 何 使 用 Jersey 完 成 REST 式 的 Web 服 务 项 目 ATUP 功 能 的 同时 ， 我 们 还 在 一 个 敏捷 的 管理 进程 中 。 本 节 将 对 Sprint1 所 完成 的 核心 功能 和 Sprint2 所 完成 的 模块 功能 进行 Scrum 的 迭代 收尾 工作 


一 一 为 客 


演示 完成 的 用 户 故 


， 并 做 本 次 Sprint 的 回顾 。 


1. 单 元 和 集成 测试 


在 用 户 验收 之 前 ， 每 次 提交 都 会 执行 单元 测试 和 集成 测试 ， 相 关 配 置 见 11.3.1 节 中 的 持续 发 布 的 “ 生 


E> 


元 测试 和 集成 测试 ”部 分 。 这 里 对 ATUP 进 行 整体 单元 测试 的 校 3 


mvn clean install -PTI 


测试 结果 如 下 所 示 。 
INFO] ------------------------------------------------------------------------ 
INFO] Reactor Summary: 
INFO 
INFO] ATUP Project Parent http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/0EBPS/Text/..http://www.hzcourse.com/resource/readBook?F 
INFO] ATUP Core http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/. .http://www.hzcourse.com/resource/readBook?path=/openr 
INFO] ATUP User http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/0EBPS/Text/..http://www.hzcourse.com/resource/readBook?path=/openr 
INFO] ATUP Device http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/. .http://www.hzcourse.com/resource/readBook?path=/ope 
INFO] ATUP Case http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/O0EBPS/Text/..http://www.hzcourse.com/resource/readBook?path=/openr 
INFO] ATUP Page http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/..http://www.hzcourse.com/resource/readBook?path=/openr 
INFO] ATUP Test Station http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/14898/OEBPS/Text/..http://www.hzcourse.com/resource/readBook?pat 
INFO] - 
INFO] BUILD SUCCESS 
INFO] 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 一 
INFO] Total time: 1:04.929s 


2. 验 收 自动 化 部 署 


本 节 将 对 自动 化 部 署 的 ATUP 进 行 全 面 的 验收 测试 ， 包 括 部 署 、 配 置 的 测试 ， 模 块 功能 点 的 测试 和 基础 功能 的 测试 。 


(1) 验收 动态 模块 


动态 模块 的 部 署 校 验方 法 是 查看 Tomcat 服 务 器 的 webapps 目 录 ， 成 功 的 部 署 应 包括 ATUP 的 4 个 REST 模 块 。 


11 /opt/tomcat7.0.34/webapps/ 
4 


Grwxrwxr-x 4 eric eric 096 Mar 1 07:49 atup-case/ 

~—rw-rw-r-- 1 eric eric 26273260 Mar 1 07:49 atup-case.war 
drwxrwxr-x 4 eric eric 4096 Mar 1 07:49 atup-device/ 
~rw-rw-r-- 1 eric eric 26260468 Mar 1 07:49 atup-device.war 
drwxrwxr-x 4 eric eric 4096 Mar 1 07:50 atup-test-station/ 
-rw-rw-r-- 1 eric eric 26255950 Mar 1 07:50 atup-test-station.war 
Grwxrwxr-x 4 eric eric 4096 Mar 1 07:48 atup-user/ 
-rw-rw-r-- 1 eric eric 26258968 Mar 1 07:48 atup-user.war 


(2) 验收 数据 库 


通过 对 数据 库 服务 器 的 检测 实现 数据 库 的 校 验 ， 最 简 脚 本 示例 如 下 。 


mysql -uroot -proot 
mysql> show databases; 
mysql> show tables; 


atup_device | 
atup user 
test_case 
test result 
test suite 


5 rows in set 
(0.00 sec 


(3) 验收 静态 模块 


静态 模块 的 部 署 校 验 是 对 Nginx 服 务 器 的 atup-page 模 块 对 应 的 目录 进行 检查 ， 成 功 的 部 署 应 包含 如 下 目录 和 文件 。 


11 ~/nginx/atup-page 


eric eric 4096 Feb 27 22:48 users/ 
eric eric 4096 Feb 27 22:48 WEB-INF/ 
eric eric 4096 Mar 1 23:50 webjars/ 


drwxr-xr-x 
Grwxr-xr-x 
Grwxr-xr-x 


drwxr-xr-x 2 eric eric 4096 Feb 27 22:48 cases/ 
drwxr-xr-x 2 eric eric 4096 Feb 27 22:48 devices/ 
-rw-r--r-- 1 eric eric 318 Mar 2 00:20 favicon.ico 
-IWw-r--r-- 1 eric eric 1160 Mar 2 00:20 index.html 
drwxr-xr-x 2 eric eric 4096 Feb 27 22:48 jobs/ 
drwxr-xr-x 7 eric eric 4096 Feb 27 22:48 js/ 
-IrWw-r--r-- 1 eric eric 1282 Mar 2 00:20 signIn.html 
-rw-r--r-- 1 eric eric 1170 Mar 2 00:20 signUp.html 
-rw-r--r-- 1 eric eric 639 Mar 2 00:20 storageTest ,html 

2 

3 

3 


(4) 验收 REST 接 口 


一 县 Tomcat 服 务 器 启动 ，REST 接 口 就 可 以 通过 WADL 进 行 校 验 ，Jersey 默 认 提供 了 WADL 的 生成 。 


//REST 

服务 WADL 

curl http://192.168.1.180:8080/atup-user/rest-api/application.wadl 
curl http://192.168.1.180:8080/atup-device/rest-api/application.wadl 
curl http://192.168.1.180:8080/atup-case/rest-api/application.wadl 


(5) 验收 登录 功能 


尝试 使 用 用 户 名 xer 和 密码 xer 登 录 ， 如 果 成 功 ， 即 表明 登录 没有 问题 了 ， 进 而 可 以 校 验 普通 用 户 可 以 查看 的 页 面 和 权限 。 


(6) 验收 添加 测试 设备 


使 用 用 户 名 atupDevicekeeper 和 密码 jaxman 登 录 ， 然 后 进入 如 下 页 面 ， 添 加 设备 。 


http://192.168.1.160/atup-page/ devices/device.html 


设备 创建 后 ， 其 状态 为 ERROR， 只 有 探测 线程 与 该 物理 设备 成 功 通 信 ， 该 设备 的 状态 才 会 更 新 为 IDLE。 下 面 是 对 这 个 功能 的 校 验 


(7) 校 验 测试 设备 状态 


首先 ， 通 过 访问 如 下 页 面 可 以 观察 设备 列表 中 各 个 设备 的 状态 信息 。 该 页 面 应 该 定时 刷新 。 


http://192.168.1.160/atup-page/devices/devices.html 


如 果 该 页 面 定时 刷新 ， 并 得 到 期 待 的 状态 ， 那 么 证 明 周期 检测 设备 状态 的 线程 工作 是 正常 的 ， 即 如 下 脚本 被 正确 执行 。 


& 


curl -X POST http://192.168.1.180:8080/atup-device/rest-api/devices/status 


(8) 验收 更 新 测试 设备 所 有 者 


的 设备 。 
http://192.168.1.160/atup-page/devices/devices.html 


选取 操作 会 访问 如 下 地 址 ， 并 携带 相关 参数 。 进 入 设备 管理 页 面 ， 将 设备 分 配 下 去 。 


户 atupDeviceKeeper 的 身份 是 设备 管理 员 ， 普 通用 户 要 创建 测试 作业 ， 就 要 持 有 测试 设备 。 因 此 ，atupDeviceKeeper 在 检测 设备 正常 后 ， 


应 分 配 设 备 给 


户 。 首 先进 入 设备 列表 页 


四 


， 选 取 待 分 派 


http://192.168.1.160/atup-page/devices/device.html?deviceIp=192.168.1.180&deviceName=&deviceType=0&deviceStatus=0&userId=4 


(9) 验收 创建 测试 用 例 


http://192.168.1.160/atup-page/cases/testCase.html 


(10) 验收 创建 测试 作业 


成 功 创建 测试 用 例 后 ， 可 以 通过 访问 测试 用 例 列表 来 校 验 ， 参 考 地 址 如 下 。 


http://192.168.1.160/atup-page/cases/testCases.html 


在 列表 页 面 中 ， 单 击 相 关 测 试用 例 ， 即 可 创建 测试 作业 ， 参 考 地 址 如 下 。 


http://192.168.1.160/atup-page/jobs/jobs Queue.html?caseld=1&caseName=abc 


(11) 校 验 测试 作业 是 否 正 确 下 发 


创建 测试 作业 后 ， 可 以 通过 待 下 发 测试 作业 列表 观察 ， 参 考 地 址 如 下 。 


http://192.168.1.160/atup-page/jobs/runningJobs.html 


户 xer 得 到 分 配 的 设备 ， 即 可 开始 创建 作业 的 流程 。 首 先是 创建 测试 用 例 ， 


地 址 如 下 。 


如 果 测 试 作业 在 列 出 后 的 下 n 个 刷新 后 消失 ， 即 认为 测试 作业 已 经 下 发 。 同 时 ， 证 明 周期 下 发 作业 的 线程 工作 正常 。 对 应 的 脚本 如 下 。 


curl -X POST http://192.168.1.180:8080/atup-case/rest-api/testjobs/jobs?count=5 


(12) 验收 测试 结果 


测试 作业 下 发 后 ， 执 行 完 毕 会 返回 测试 结果 。 通 过 如 下 地 址 检测 测试 作业 的 结果 。 如 果 已 经 列 出 ， 证 明 整 个 测试 作业 流程 结束 。 


http://192.168.1.160/atup-page/cases/testResults.html 


(13) 验收 服务 器 日 志 


在 测试 流程 的 同时 ， 我 们 可 以 通过 服务 器 上 各 个 模块 的 独立 日 志文 件 来 观察 运行 情况 。 这 一 检测 也 是 对 ATUP 中 Log4j 2 的 使 用 的 校 验 。 相 关 日 志文 件 如 下 。 


ls /home/eric/atup 1og 
atup case.log atup device.log atup user.log 


静态 模块 的 日 志 可 以 参考 Nginx 的 访问 日 志和 错误 日 志 来 检测 。 


ls /usr/local/nginx/logs 
error.10g access.1og 


11.3.4 Sprint 3 持续 交付 


在 完成 基础 功能 和 模块 功能 后 ，ATUP 的 开发 工作 基本 已 经 完成 ， 新 的 Sprint 的 重点 放 到 了 持续 集成 测试 上 。 当 然 ， 这 期 间 通 常会 夹杂 着 小 功能 的 开发 和 缺陷 的 修复 ， 因 此 ， 在 这 一 过 程 中 ， 小 步 、 快 速 


地 进行 持续 集成 便 是 重点 。 


同 


1. 持 续集 成 


ATUP 的 Maven 配 置 完成 后 ， 应 使 用 Jenkins 的 job 来 触发 而 不 是 在 终端 中 手动 执行 。 一 个 完整 的 持续 集成 (Cl) 和 持续 交付 (CD) 流程 如 图 11-11 所 示 。 


色 11-10 展 示 了 整个 持续 交付 的 过 程 。 持 续 交 付 是 持续 集成 的 延伸 和 最 终 目的 ， 在 图 11-11 中 ，Nexus 是 Maven 私 有 仓库 的 一 种 ，Gitolite 是 Git 的 私有 服务 器 。CI 流 程 的 第 一 个 关键 点 是 Git 的 hook 脚 
本 。 当 开发 者 提交 代码 到 Gitolite 服 务 器 后 ， 会 触发 post receive 脚 本 ， 该 脚本 中 定义 了 对 Jenkins 指 定 job 的 访问 。 在 Jenkins 一 端 ， 配 置 了 Maven 命 令 ， 即 前 面 使 用 的 Maven 命 令 。 这 期 间 ， 代 码 覆盖 工具 


Cobertura 和 代码 质量 检查 工具 sonarQube 会 被 Jenkins 的 job 调用 ， 生 成 相关 报告 。 最 后 ， 构 建成 功 后 会 执行 前 面 讲 过 的 部 署 操 作 。 


在 简要 了 解 了 CI 流程 后 ， 回 头 观察 ，CI 流 程 的 发 起 是 开发 者 的 提交 操作 。 因 此 ，Sprint3 的 工作 比 起 前 面 的 方式 ， 在 敏捷 和 自动 化 测试 上 都 更 好 。 这 里 不 再 深入 研究 如 何 实现 各 个 服务 器 的 搭建 和 配置 ， 


读者 可 自行 实现 ， 以 深入 理解 和 掌握 相关 原理 和 细节 。 


2. 分 模块 部 署 


192.168.1.161。 修 改 jax-rs2-atup\atup-page\src\main\webapp\js\atupCommon _staging.js 文 件 ， 参 考 代码 如 下 。 


var ATUP USER HOST = "http://192.168.1.181:8080/"; 
var ATUP CASE HOST = "http://192.168.1.182:8080/"; 
Var ATUP DEVICE HOST = "http://192.168.1.183:8080/"; 
Var ATUP_ PAGE HOST = "http://192.168.1.161/"; 


部 署 时 ， 提 供 动态 的 服务 器 地 址 参数 ， 示 例 代码 如 下 。 


mvn clean install -DskipTests -Dmysql.server.ip=192.168.1.181 -PCI 


3. 灰 度 发 布 


CI 起 始 于 开发 者 的 提交 带 来 的 好 处 是 ， 新 的 功能 和 改变 可 以 很 快 上 线 ， 让 
的 稳定 性 和 伸缩 性 带 来 了 更 多 的 支持 。 


户 第 一 时 间 验 收 。 通 过 在 代码 中 使 用 switch 和 动态 指定 服务 器 地 址 可 以 使 指定 服务 器 为 指定 人 群 开放 指定 的 功能 。 这 对 系统 


ATUP 采 用 多 staging 的 方式 提供 不 同 用 户 组 不 同 功能 的 部 署 模 式 ， 这 里 不 再 展开 介绍 。 
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图 11-11 持续 交付 流程 示意 图 


4.lteration2 的 演示 和 回顾 


相 较 于 lteration1 的 验收 测试 ，lteration2 给 出 了 更 自动 化 的 方式 。 因 为 前 者 的 部 署 是 通过 Maven 命 令 执行 的 构建 和 部 署 ， 而 后 者 是 通过 CI 流程 /工具 完成 的 一 键 式 部 署 。 


lteration2 的 验收 包括 CI 流程 中 各 个 服务 器 的 配置 和 基本 功能 的 验证 、CI 流 程 的 完整 性 、CI 结 果 的 完整 性 等 。 这 超出 了 ATUP 功 能 本 身 的 讲述 范围 。 


11.3.5 ”交付 和 总 结 


经 过 了 三 个 Sprint 的 敏捷 开发 ， 我 们 演示 了 开发 一 个 REST 式 的 Web 服 务 的 全 过 程 。 虽 然 ，ATUP 是 不 太 完善 的 ， 但 它 是 可 用 的 。 敏 捷 带 给 我 们 的 思想 是 简单 ， 我 们 从 简单 的 设计 和 实现 入 手 ， 经 过 不 断 
迭代， 持续 重 构 和 完善 既 有 产品 及 其 设计 。 如 果 再 扩展 去 谈 敏捷 ， 就 超出 了 本 书 的 范围 。 下 面 将 就 此 展望 一 人 ATUP 的 下 一 个 迭代 。 


(1) 下 一 个 迭代 


针对 代码 覆盖 率 和 代码 质量 ， 开 发 团队 内 部 比 谁 都 清楚 该 如 何 提高 。 与 此 同时 ， 来 自 客户 的 新 功能 和 已 有 功能 的 改进 对 ATUP 既 有 代码 的 重 构 和 实现 会 提出 新 的 挑战 。 这 些 都 是 未 来 迭代 需要 实践 的 。 


(2) 重 构 


中 | 


代码 重 构 是 敏捷 实践 不 可 或 缺 的 环节 。 作 为 开发 者 ， 我 们 必须 知道 


构 经 验 。 


1) sonarQube: 为 


户 提供 评分 和 改进 方案 是 这 款 质 量 保证 平台 最 有 价值 的 地 方 之 一 。 开 发 者 可 以 从 中 


哪里 应 该 重 构 。 除 了 不 断 阅读 Java 编 程 规范 、 


2) Profiler: JVM 的 Profiler 工 . 


是 ATUP 出 现 性 能 问题 时 需 


考虑 使 用 的 ， 


3) Probe: Probe 这 类 运行 时 服务 器 监控 


11.4 本章 小 结 


对 辅助 了 解 运行 时 资源 使 有 


我 提高 。 


这 样 可 以 尽快 定位 实现 过 程 中 “制造 ”的 问题 。 


情况 非常 有 帮助 。 如 果 ATUP 系 统 不 能 良好 运行 ， 则 可 以 阶段 性 地 考虑 使 


重 构 和 设计 模式 等 经 典 著作 ， 我 们 也 应 (借助 如 下 工 


， 以 排查 问题 。 


) 从 实践 中 总 结 出 自己 的 设计 和 


本 章 讲 述 了 一 个 完整 的 REST 式 的 Web 服 务 的 实现 全 过 程 ， 结 合 Scrum 敏 捷 实 践 ， 对 ATUP 平 台 的 需求 、 设 计 和 编码 、 测 试 、 发 布 进行 了 详细 的 讲述 。 此 外 ， 讲 述 了 REST 开 发 的 大 环境 ， 包 括 小 步 迭 代 中 


从 REST 和 JAX-RS 的 人 


度 来 看 Web 开 发 的 发 展 时 ， 我 们 可 以 从 C/S 


工作 的 。 


从 胖 客 户 端 到 疤 客 户 端 


对 于 开发 和 维护 者 来 说 ， 客 
台 使 


那么 多 的 


社 
分 


胖 客 户 端 指 的 是 C/S (Client/Server) 架构 中 的 Client。C/S 时 期 是 以 Windows 为 代表 的 桌面 应 F 
转向 B/S 


界面 的 用 户 体验 比 后 来 的 B/S 结构 更 


的 持续 集成 CI) 流程 及 工具 、 重 构 和 螺旋 式 提高 代码 质量 的 心得 分 享 。 


附录 “Web 简 史 


(Client/Server) 时 期 开始 简单 回顾 ， 即 可 更 清楚 地 明 


(Browser/Server) 时 期 的 “旗手 ”。 相 对 于 今天 的 浏览 器 (客户 端 ) ，C/S 时 期 的 客户 端 称 为 胖 客户 端 ， 
优势 ， 使 服务 器 专注 于 处 理 数据 。 


因为 Client 维 护 着 


户 的 会 话 信息 和 交互 信息 ， 对 了 


白 REST 在 Web 领 域 为 何 成 为 一 种 趋势 ， 以 及 如 何 与 那些 息息相关 的 技术 集 协 同 


时 代 ， 也 是 VB、Delphi 盛 行 的 时 期 。Java 领 域 的 Applet 是 这 个 时 期 的 后 起 之 秀 ， 并 成 为 引领 C/S 时 期 
数据 校 验 、 缓 存 等 功能 “亲历 亲 


从 C/S 到 B/S 的 转型 是 网 络 时代 崛 起 的 标志 和 必然 趋势 。 胖 客户 端 明显 的 缺点 是 它 必须 安装 到 客户 端 本 地 。 虽 然 Applet 没 有 一 个 明显 的 安装 客户 端的 过 程 ， 但 也 需要 本 地 Java 运 行 环境 (JRE) 的 支持 。 


是 一 种 奢望 ， 胖 客户 端 对 操作 系统 有 依赖 ， 甚 至 会 陷入 DLL 窒 境 ， 


户 端的 多 版 本 共存 和 升级 就 是 “无 尽 ”的 任务 。 对 于 


户 来 说 ， 最 不 情愿 的 村 


情 就 是 被 迫 升级 本 地 的 客 


但 这 一 问题 在 浏览 器 作为 客户 端的 B/S 时 期 荡然 无 存 。 


从 瘦 客 户 端 #| 语 客户 端 


器 必要 的 “ 累 歼 ”， 用 户 的 每 一 次 交互 都 要 交 由 服务 器 处 理 ， 甚 至 是 验证 输入 框 信息 这 么 小 的 一 个 交互 ， 包 括 这 期 间 的 时 延 等 带 来 的 
除了 处 理 提交 和 展示 服务 器 返回 的 信息 以 外 几乎 什么 也 没有 。 时 代 的 选择 是 让 客户 端 “ 富 ” 


时 至 今日 ，B/S 依 然 流 行 ， 但 B/S 结构 并 没有 停留 在 开始 的 瘦 客 户 端 阶段 。 把 工作 都 交 给 服务 器 是 瘦 客 户 端 的 初 衣 ， 同 时 ， 这 样 的 想法 也 是 一 把 “ 双 丸 剑 ”。 由 于 


因此 ，B/S 应 运 而 生 。B/S 无 须 安装 ， 打 开 浏 览 器 ， 输 入 网 址 就 可 以 进入 应 
有 情 呢 ? 把 它 交 给 服务 器 吧 。 在 Java 领 域 ， 以 Servlet 和 JSP 为 基础 的 瘦 客 户 端 
引入 了 模板 、 标 签 等 技术 。B/S 茵 勃发 展 ， 并 且 促使 )ava 的 标准 随 之 而 动 
区 和 标准 组 织 不 断 出 台 的 、 相 互 协 作 、 相 互 促进 的 框架 和 技术 使 得 瘦 客 
层 逻 辑 中 收益 的 绝 不 只 是 开发 工程 师 ， 还 有 质量 保证 工程 师 、 运 维 工程 师 ， 甚 至 整个 研发 团队 。 


。 B/S 的 出 现 更 重 


的 开发 过 程 让 “ 富 ” 起 来 的 客 


AJAX 是 这 个 阶段 比较 成 功 的 代表 。 异 步 请 求 和 DOM 的 动态 改写 带 来 了 页 面 的 局 部 刷新 ，Dojo 和 jQuery 为 代表 的 Java Scrpit 库 为 客户 端 带 来 了 


起 来 。 


AJAX 的 出 现 其 实 是 一 件 水 到 渠 成 的 事情 。 因 为 在 这 期 间 ， 许 多 技术 严谨 、 不 拘 一 格 的 开发 者 在 为 JavaScript 贡 献 着 开源 JavaScript 库 ， 这 些 优秀 


户 端 “活力 四 射 ”。 客 户 端 开发 的 发 展 不 是 


度 发 


户 端 走 上 历史 的 顶峰 。 开 发 过 程 变 得 富有 哲理 和 艺术 气息 ， 分 


户 端 版 本 ， 而 且 每 当 切 换 操作 系统 ， 就 要 重新 安装 一 次 客户 端 。 至 于 跨 平 


的 原因 是 实现 那个 时 期 的 一 个 愿望 : 那个 时 期 的 服务 器 端 编程 已 经 非常 强大 ， 我 们 为 什么 要 让 客户 端 做 
发 逐渐 成 熟 ，Struts 带 来 了 MVC，Spring 带 来 了 loC 和 AOP，Hibernate 带 来 了 O/R-Mapping， 
，Struts 和 Spring 促 成 了 JSF 的 诞生 ，Spring 改 变 了 EJB 在 3.0 之 后 的 命运 ，Hibernate 促 成 了 Java 领 域 的 数据 库 访问 新 标准 JPA。Java 


“瘦小 ”的 前 端 也 


层 开发 有 利于 解 厢 ， 易 于 梳理 和 定位 异常 和 缺陷 。 我 们 可 以 想象 ， 从 


FHTTP 是 无 状态 的 ，Session 成 为 了 服务 
户 体验 非常 糟糕 。 瘦 客户 端 ， 从 另 一 个 角度 看 是 一 个 “ 穷 客户 端 ”， 


F 富 的 组 件 和 皮肤 
“ 腾 ” 而 走向 倒退 ， 而 是 在 坚持 B/S 结构 的 同时 ， 使 之 功能 强大 起 来 。 


的 JS 库 不 仅 是 工 


风格 ， 


包 ， 


良好 的 用 户 体验 和 更 为 轻松 愉快 


其 中 包含 了 许多 引领 时 代 发 展 的 


思想 和 技术 。 虽 然 富 客户 端的 美学 因素 让 开发 十 分 慨 意 ， 但 跨 浏览 器 开发 中 ， 样 式 和 事件 的 调试 和 测试 是 极其 专业 的 事情 ， 再 不 是 一 个 进行 过 后 台 开 发 就 能 上 来 摆弄 前 端的 时 代 了 。AJAX 的 出 现成 就 了 许多 


专业 的 前 端 开发 者 ， 从 这 个 时 期 开始 ， 前 端 开 发 的 技术 含量 逐日 增加 ， 前 端 开 发 工程 师 也 开始 被 业内 更 多 地 认可 和 尊 


模式 使 得 富 客 


另 一 个 代表 是 JSF。JSF 是 Java 领 域 的 一 个 标准 , 采 


浏览 器 端的 


件 驱 动 的 机 


制 ， 它 吸收 了 Spring 和 AJAX 的 精华 ， 是 Java 领 域 中 最 
户 端 开 发 变 得 快速 和 一 致 。 需 要 提 及 的 是 ，XHTML 在 JSF 领 域 得 到 了 重视 和 推动 。JSF 的 缺点 是 设计 上 不 够 轻 量 ， 入 门 的 起 点 较 高 ， 其 广泛 性 也 远 远 不 如 Spring 等 。 


由 


ASP.NET 风 范 的 技术 框架 。 其 全 栈 式 的 


看 。AJAX 在 很 大 程度 上 会 推动 Web 开 发 的 未 来 ， 包 括 单 页 面 技术 、 平 庸 客户 端 。 


发 框架 和 组 件 的 生命 周期 


还 有 一 组 代表 是 JavaFX、Flex， 以 及 微软 公司 的 Silverlight 这 样 的 技术 。 富 客户 端 这 个 时 期 并 没有 结束 ， 但 同属 RIA (Rich Internet Applications) 时 期 的 Flash， 由 于 市 场 的 原因 ， 对 开发 团队 和 开发 
者 来 说 ， 也 许 会 考虑 其 投资 回报 率 和 风险 。 


从 语 客 户 端 到 “平庸 ”的 客户 端 


“平庸 ”的 纯 HTML 网 页 可 以 做 的 事情 主要 是 通过 HTML 标 签 来 展示 数据 。 纯 HTML+AJAX 的 功能 是 发 出 HTTP 请 求 并 局 部 刷新 页 面 ， 
局 限 性 ,我 们 必须 引入 脚本 语言 (ASP、PHP、JSP 等 ) 来 “壮大 ”客户 端 。 而 有 了 REST， 这 和 


似 变 弱 的 变化 ， 有 什么 意义 呢 ? 


平庸 的 客户 端 带 来 的 是 一 个 Web 发 展 的 新 时 期 。 这 个 时 期 ， 客 户 端 不 仅 是 平台 无 关 的 ， 而 
DEMO 包 里 F 


不 需要 区 分 PHP、JSP、ASP.NET 版 本 ， 只 需要 提供 HTM 


解 耦 是 平庸 客户 端 最 明显 的 优势 。 松 散 的 耦合 使 开发 难度 降低 ， 系 统 的 水 平 扩 


交互 的 是 REST 接 


其 开发 成 本 大 大 降低 。 从 部 署 上 看 ， 纯 HTML 的 客 


版本， 甚至 是 cURL 脚本 或 者 Shell 脚 本 。 


展示 服务 器 返回 
平庸 的 客户 端 就 可 以 完成 更 多 的 业务 逻辑 功能 。 因 


展 能 力 增强 。 从 代码 耦合 上 看 ， 纯 HTML 的 客户 端 开 发 并 不 关心 服务 器 端 使 
户 端 是 静态 页 面 ， 可 以 部 署 在 以 Nginx 为 代表 的 HTTP 服 务 器 上 ， 有 效 地 降低 了 应 用 服务 器 的 负载 。 富 客户 端 在 这 方面 是 束手无策 的 ， 


的 数据 。 这 样 的 客户 端 在 REST 出 现 之 前 ,似乎 太 有 
为 REST 式 的 Web 服 务 公布 的 就 是 简单 的 HTTP 请 求 。 这 看 


是 语言 无 关 的 ， 这 样 的 客户 端 可 以 实现 对 任何 一 种 编程 语言 实现 的 REST 服 务 器 的 请 求 。REST 服 务 提供 者 的 


的 是 哪 一 种 编程 语言 ， 


唯一 需要 和 服务 器 端 


动态 脚本 不 仅 有 性 能 问题 ， 而 且 在 部 署 过 程 中 ， 很 难 实现 和 服务 器 端 代码 分 离 。 


平庸 客户 端 带 来 的 思考 是 ， 前 端 为 何 走向 平庸 (包括 美术 风格 上 的 扁平 ) 。 


面 对 敏 捷 和 持续 集成 、 持 续 部 署 和 持续 交付 ， 纯 HTML 的 客户 端 可 以 轻松 地 以 独立 的 模块 作为 被 测试 和 部 署 的 基本 单位 。 


Web 发 展 过 程 中 ， 始 终 不 是 孤立 的 ， 在 C/S 时 期 ， 移 动 设备 有 Java ME; 在 MVC 流 行 的 时 期 ， 设 计 者 和 开发 者 在 开发 Web 的 


同时 ，Wap 版 本 占据 着 一 席 之 地 ;， 从 移动 2.5+G 时 代 开 始 ，iOS 和 Android 占 据 的 社交 网 络 、 电 子 商 务 等 领域 的 市 场 配 额 逐步 增加 ，“ 短 平 快 ”成 为 趋势 。 我 们 所 关注 的 不 局 限于 Web 页 面 如 何 解读 复杂 业 
务 ,而 是 关注 服务 器 和 客户 端 之 间 如 何 快速 通信 、 快 速 响应 。AJAX 不 是 终点 ， 


它 虽 然 解决 了 客户 端 异 步 请 求 问 题 ， 但 网 络 10 依 然 是 阻塞 的 ， 下 一 个 主题 会 是 什么 呢 ? 相 信 会 覆盖 到 HTML5 以 及 与 之 并 行 的 


服务 器 推送 技术 和 服务 器 异步 、 非 阻塞 |O。 与 此 同时 ,平庸 的 客户 端 也 会 出 现 新 的 特性 ， 尤 其 是 作为 配合 服务 器 新 特性 的 展示 层 ， 比 如 Web Socket 以 及 与 之 并 行 的 Server Push Taglib、JS 库 的 Comet 支 


持 。 


在 基于 Jersey 的 实现 中 ，REST 风 格 的 应 


经 具备 了 异步 处 理 请 求 、 非 阻塞 式 读 写 、 动 静 分 离 等 特征 。 同 时 ， 可 以 很 好 地 与 Web Socket、SSE 等 HTML5 特 征 协同 工作 。 
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作为 技术 人 员 ， 你 的 头衔 可 能 是 技术 总 监 、 
序 员 。 


滞 


后 记 


架构 师 、 技 术 主管 ， 或 者 高 级 开发 工程 师 、 开 发 工程 师 等 ， 请 别 嫌弃 作为 程序 员 的 这 个 身份 。 我 喜欢 学 着 《喜剧 之 王 》 里 尹 天 仇 的 口吻 说 ， 其 实 我 是 一 个 程 


为 ， 程 序 员 这 个 身份 是 上 述 头 衔 去 除名 和 利之 后 的 本 质 。 


诚然 ， 技 术 总 监 可 以 是 从 系统 工程 师 、 质 量 保证 工程 师 提 升 上 来 的 ， 他 们 懂 工 程 ， 懂 质量 保障 ， 但 是 一 名 合格 的 CTO， 他 必须 懂 开 发 。 所 以 ， 我 坚信 他 是 自己 人 。 


身 为 程序 员 ， 首 先 应 该 具备 的 素质 就 是 持续 学 习 。 


因为 “ 码 ” 这 个 瞬间 动词 需要 “厚积薄发 ”这 个 持续 的 形容 词 来 做 基础 ， 知 识 的 积累 和 梳理 需要 你 不 间断 地 学 习 、 实 践 和 思考 。 另 一 个 素质 是 “站 


队 ” 和 甄别 。 “站队 ” (选择 某 种 技术 ) 需要 有 一 定 的 积累 ， 你 会 知道 什么 技术 是 有 发 展 的 ， 因 为 技术 层出不穷 ， 你 不 可 能 都 去 学 习 ， 一 要 根据 兴趣 ， 二 要 看 清 未 来 的 发 展 趋 势 。 甄 别 是 要 懂得 学 什么 ， 是 


学 原理 和 规范 还 是 学 工具 和 实例 。 我 曾经 目睹 某 位 Android 的 工程 师 在 不 了 解 Java 的 设计 模式 的 情况 下 ， 误 读 内 部 架构 的 设计 。 我 们 要 做 好 程序 员 ， 一 定 要 “ 知 其 然 ， 知 其 所 以 然 ”， 否 则 很 难 成 长 ， 纵 然 


你 很 努力 。 


选择 本 书 的 读者 一 定 是 在 持续 学 习 的 人 ， 你 站 在 了 java 和 REST 的 “队伍 ”里 。 你 第 一 步 要 做 的 是 知识 的 积累 ， 即 看 完 这 本 书 ， 然 后 是 梳理 ， 按 照 你 对 JAX-RS 的 理解 完成 书 里 的 例子 ， 同 时 做 笔记 。 建 议 
在 掌握 本 书 内 容 后 ， 去 做 两 件 事 : 翻 看 一 下 JSR 339， 它 是 Java API for RESTful Web Services 的 技术 规范 ;再 查看 一 下 Jersey 的 源 代码 ， 它 是 JSR 339 规 范 的 实现 ， 你 可 以 从 中 了 解 到 如 何 使 用 Java 的 技术 


来 实现 一 个 规范 。 本 书 涉及 jQuery、Dojo 等 工 


， 如 果 你 懂得 甄别 的 话 ， 那 么 对 工具 的 学 习 应 该 是 够 用 就 好 。 


